Agents from the command line

One agent with a job, the services it may use and a budget you set (nothing is filled in for you); you run it and read its receipts. Then a second agent hires the first: an agent network. Everything that governs an agent is set when you create it, budget included. Nothing is charged until it runs, and it never spends past its caps, which the runner enforces, not the AI. Every command talks to the agent runner; the agents it makes are the ones the app's Agents page shows.

What you need

The CLI, with the stack running: your own runner, inside your private node, answers at AIOUM_AGENTS_URL (http://127.0.0.1:8770/runner) with the node's token.
For an agent that plans with AI (--mode assistant), a model: a planner listing on the marketplace (npx aioum planners lists them; anyone can run one, the agent pays it per turn), a local Ollama beside the runner, which it picks up on its own, or a key on the runner, ANTHROPIC_API_KEY=… scripts/devstack.sh review. Without any, use --mode workflow (fixed steps) or the price-check starter, which needs no AI.
No wallet to set up: agents pay from the wallet on your node. On the local development network the node makes one and funds it with test USDC.
AIOUM_OWNER (default cli) is the name your agents are grouped under; npx aioum agents lists that group.

Steps

See the tools an agent can pay for.
```
npx aioum tools --q price
```
One row per tool whose words match: the service id, the tool's name, the service's name and category, the price per call, whether it is live and what the tool does. Note the serviceId:tool pairs you want; the next commands take them in that form. --refresh makes the runner re-read the directory first.
See the ready-made agents.
```
npx aioum starters
```
One row each: the id, group, name and mode, whether it is available with the listings live right now (and what is missing when it is not), how many tools it resolved, and its tagline. The ids are morning-brief, token-scanner, swap-router, best-rate-swap, bridge-quote, prediction-odds, wallet-watch, news-digest, community-poster, price-check, fear-greed-log and tune-machine.
Create an agent from flags.
```
npx aioum agent create --name "Morning brief" --mode assistant \
  --instructions "Write a morning crypto brief: top coins, 24h change, two headlines." \
  --tools "<serviceId>:markets,<serviceId>:trending" --access prefer --deny "<serviceId>" \
  --cap 5 --per-run 0.25
```
--mode is assistant (an AI model reads the instructions and chooses which tools to call) or workflow (fixed steps, the same result every time; the steps come from a file). --access is how it picks services: only the ones in --tools, prefer them and search the marketplace for more when the job needs it, or open, no picks, it finds everything itself. --deny lists service ids (and skill ids) it must never use, whatever it finds. --skills a,b adds skills by id, from npx aioum skills --q <words> (the open-source index with each repo and licence, and skills listed on nodes with their terms) or svc:<serviceId> for a listed one, and --skills-access only|prefer|open says how it reaches them (prefer by default); --data-access only|prefer|open does the same for the memory and workspace files on your node. A tool on your private node is local:<tool> in --tools, free. --cap is the lifetime budget in USDC and --per-run the most one run may spend, both required to create (without them: agent create needs --cap and --per-run, in USDC, both above zero (or budget in --file): Set the budget you are willing to spend, and nothing is sent); --pay-across on|off (on by default) lets the wallet on your node swap what it holds into USDC at the best rate when the runner's wallet is short for a call, within the wallet's caps (Swap at the best rate); --schedule-every <minutes> with --schedule-input "…" adds a schedule at the same time. --planner-service <id> plans through that marketplace listing, paid per turn from the agent's budget; --planner anthropic or openai pins the runner's own model (auto otherwise). It prints created agent <id> and the agent's name, mode, access, planner, tools, budget and schedule; keep that id.

Or create it from a file, with the same fields as JSON. The runner adds owner from AIOUM_OWNER. A workflow agent lists its steps here, each with a tool and args templates, and an optional outputTemplate; a schedule (everyMinutes, input, enabled) is optional in either mode.

{
  "name": "Morning brief",
  "description": "Prices, movers and headlines in one message.",
  "instructions": "Write a morning crypto brief: top coins, 24h change, and two headlines.",
  "mode": "assistant",
  "planner": "auto",
  "tools": [
    { "serviceId": "<serviceId>", "tool": "markets" },
    { "serviceId": "<serviceId>", "tool": "trending" }
  ],
  "access": "prefer",
  "deny": ["<serviceId>"],
  "budget": { "capUsdc": 5, "perRunMaxUsdc": 0.25 }
}

npx aioum agent create --file spec.json

A flag on the same command overrides that field of the file.

Or start from a ready-made one, with your two caps.
```
npx aioum agent create --starter price-check --cap 2 --per-run 0.05
```
The CLI copies the starter's name, words, mode, tools and steps, resolved against the listings live right now, and creates it; a starter carries no budget, so --cap and --per-run are yours, and a flag overrides what it copied (--name to call it something else). price-check is a two-step workflow, fetch a price then format it, with no AI.

Or say the job and the budget in one command and let the runner build the Super Agent for it, fully loose on services, skills and data, with the best live planner (the highest model tier live: a 7B model beside the runner over a 3B listing) and a project whose stages that planner proposes:
```
npx aioum super --prompt "Make me a 1 minute cartoon clip similar to South Park" --budget 25
```
It prints created super agent <id>: 1 minute cartoon clip similar to South Park, plans with the planner and why, the project's stages, and started: follow it with aioum project get <id>; --draft shows the stages without starting, --planner marketplace:<id>|anthropic|openai picks the planner yourself. Without --budget it answers super needs --budget <usdc>, above zero: Set the budget you are willing to spend.
Run it and wait.
```
npx aioum agent run <agent-id> --input "Give me this morning's brief." --wait
```
The run starts at once; with --wait the CLI polls until it is done, failed or stopped (--timeout in seconds, 600 by default) and prints the run: its id, agent, status, how it started, when it started and finished, the input, what it spent in USDC, how many calls it made, and the output. Without --wait it prints the new run and returns; without --input the agent follows its instructions with nothing asked. An agent with a run still going answers this agent is already running.
List the runs.
```
npx aioum runs --agent <agent-id>
```
The latest thirty (--limit for more), one row each: run id, agent, status, how it started (manual, schedule or service, the last meaning another caller hired it), when it started and finished, what it spent and how many calls it made. Without --agent it lists every agent's runs.
Read one run's log.
```
npx aioum run get <run-id>
```
The run in full. Its steps, in order, each with its time, its kind and what happened: info (the budget for this run), search (what it looked for on the marketplace and what it found), thought (the model's notes), tool (a paid call: the tool and the service, the cost in USDC, how long it took and the start of the result), rating (the score it gave the operator, 0 to 100, from the calls, errors and slow answers it saw), final (the answer) or error. Then its sessions, the receipts: one per service, with the session id, what was spent, the calls, whether it settled and the settlement transaction. Last, the output. --json has the rest: each call's arguments and full result, what was set aside, the errors and slow answers, and the rating with its transaction. npx aioum run stop <run-id> stops a run that is still going. npx aioum run watch <run-id> shows a run as it happens: one line per step with what the agent is doing, in plain words, and what it cost (a Local · step on your node costs nothing, a Skill · step shows the skill and its price), then what it spent per service; npx aioum run spend <run-id> and npx aioum agent spend <id> --period 24h give the breakdowns on their own (Watch it work).
Put it on a schedule.
```
npx aioum agent schedule <agent-id> --every 60 --input "Give me this morning's brief."
```
The runner runs it every 60 minutes with that input, within the same caps; the CLI prints the agent's id and its schedule. npx aioum agent schedule <agent-id> --off pauses it.
Change it later.
```
npx aioum agent update <agent-id> --cap 10 --per-run 0.5
```
Any of the create flags, or --file, changes just those fields; it prints updated agent <id> and the agent as it is now. npx aioum agent get <agent-id> shows it in full at any time, and npx aioum agents lists all of yours with their run counts and lifetime spend.
Make it a network: publish the agent as a service. The node stakes and registers it on-chain.
```
npx aioum agent publish <agent-id> --price 0.05 --stake 12000
```
Set the price above what one run costs you. It prints published agent <id> and the listing: the service id, its key (agent-<name>-<tail of the id>), the price, the category (agent:<name>), the node's URL and when. The runner refreshes its own tool catalogue, so the next step finds it.
See the first agent as a tool.
```
npx aioum tools --q "morning brief"
```
One row: the agent's service id, its category agent:morning-brief, and a tool named morning-brief that takes input. Note the pair.

Build the second agent, with the first among its tools and a per-run cap that covers its price.

npx aioum agent create --name "Desk" --mode assistant --access prefer \
  --instructions "Get the morning brief, then add one line on what to watch today." \
  --tools "<published-service-id>:morning-brief" --cap 5 --per-run 0.5

Run the second agent.
```
npx aioum agent run <second-agent-id> --wait
```
npx aioum run get <run-id> on that run shows a tool step paying the first agent at the price you set, with a receipt like any other paid call. npx aioum runs --agent <agent-id> for the first agent shows a new run started by service: it paid for its own tools from its own budget, and the difference between its price and that cost is yours.
Take it off the market, and clean up.
```
npx aioum agent unpublish <agent-id>
```
The listing is delisted and the CLI prints unpublished agent <id>. An agent never hires itself, and npx aioum agent delete <agent-id> refuses while it is published, with unpublish this agent before deleting it (its listing is live on the network); afterwards it prints deleted agent <id>.

What you have now

Two agents on the network: one with a job, a budget and the services it may and may not use, published at a price per call; one that hires it, pays with a receipt and rates the operator behind it, as it would any service. Every run, call, deposit and refund is one run get away, in the records the app's Agents and Activity pages show; every cap is enforced by the runner, not the AI.

Next: Pipelines from the command line — what each pipeline needs, one command to build the network and its project, one to start it.

AIOUM Documentation

Agents from the command line

What you need

Steps

What you have now