agentrun-cli git:20261107.cd74d06A

Immutable. This exact content never changes and is served at /api/v1/blob/3d377dcb80ad2aa3.

---
name: agentrun-cli
description: Drive an AgentRun server from a shell with the agentrun CLI. Make an agent from a definition file, start a run with a spend cap and wait for it, answer a run that asks a question, read the files it wrote and what it cost, save tool keys, and call any other route of the server. Use when asked to run or manage AgentRun agents from the terminal or a script, or for anything the server's MCP tools do not cover (files, tool keys, triggers, webhooks, revisions, learning).
---
<!-- Generated by scripts/generate-clients.mjs from the server's OpenAPI document and its skill template. Do not edit: run node scripts/generate-clients.mjs. -->
<!-- SHA-256 of what the command table is made of (operationsOf in scripts/generate-clients.mjs): 2e46b4af61eaec8d1d382d24c000ff27f21e073ccd1e9d8899d9e679fac9b936 -->

# AgentRun CLI

`agentrun` drives an AgentRun server (the open platform's server for agents) through its API. It is the command `npm install -g @parcha/agentrun` puts on the PATH; without it, write `npx @parcha/agentrun` in its place. Each command prints the server's JSON answer on stdout, one line when piped, and an error's JSON on stderr. `agentrun help` lists the commands, `agentrun GROUP COMMAND --help` gives one's flags, and [references/commands.md](references/commands.md) has every command with its flags and route.

## The server and the token

The first of these that is set wins:

1. `--base-url URL` (the API, ending `/v2`), else `AGENTRUN_BASE_URL`, with the token in `AGENTRUN_API_KEY`.
2. The config file `$XDG_CONFIG_HOME/agentrun/config.json` (else `~/.config/agentrun/config.json`), written by `agentrun login`, which checks the token first. The CLI refuses the file if anyone else can read it.
3. The server started on this machine with `npx @parcha/agentrun`, whose data directory (`~/.agentrun`, or `--data DIR`) says where it listens and holds its token: nothing to set.

The token goes on stdin, never on the command line:

```sh
agentrun login --base-url "$AGENTRUN_BASE_URL" < token.txt
```

Never print, echo or log the token, and never pass it as an argument; the CLI never prints it. `agentrun logout` removes the config file. A tool key's value is read the same way, from stdin or a variable you name: `agentrun tool-keys set KEY_ID FIELD --from-env VAR` (`agentrun tool-keys list` names the keys and fields, never a value).

## Recipes

Run them in order, in one working directory: each writes `run.json`, the run as its command printed it, and the next reads it. The last line of each block says how its last command exits.

### 1. Make an agent from a definition file

```sh
cat > agent.json <<'EOF'
{"definition": {"id": "notes", "version": 1, "name": "Notes", "instructions": "Do what you are asked, and write what you make to a file.", "skills": [], "tools": ["write", "ask_person"]}}
EOF
agentrun agents create --body @agent.json
# exit 0: the agent; exit 1 with error.code agent_exists: agentrun agents update notes --body @agent.json makes its next revision
```

Ask the person before you create or change an agent. `agentrun server capabilities` lists the harnesses, models and tools this server has.

### 2. Start a run with a spend cap and wait for it

```sh
agentrun runs start notes --max-cost-usd 5 --body '{"input": {"content": "Write notes.md with three facts about the Moon."}}' --wait > run.json
# exit 0 completed (result.final_answer); 1 failed or cancelled (error says why); 8 it waits on a person (recipe 3)
```

`--wait` follows the run until it ends or needs a person, and `--timeout SECONDS` stops waiting (exit 1, the run goes on). `agentrun runs wait RUN_ID` waits again; `agentrun runs timeline RUN_ID --follow` prints each step as it comes.

### 3. Answer a run that asks

```sh
agentrun runs start notes --max-cost-usd 5 --body '{"input": {"content": "Ask me which region to cover, then write region.md about it."}}' --wait > run.json
# exit 8: it waits on a person; run.json has pending.kind question and pending.question, what it asks
```

Answer only what the person told you, or ask them. Then:

```sh
run=$(node -p 'require("./run.json").run_id')
agentrun runs message "$run" --content "Europe"
agentrun runs wait "$run" > run.json
# exit 0 completed, as in recipe 2
```

### 4. Read what it wrote and what it cost

```sh
run=$(node -p 'require("./run.json").run_id')
agentrun runs files "$run"
agentrun runs read-file "$run" region.md
agentrun runs get "$run" > run.json && node -p 'JSON.stringify(require("./run.json").cost)'
# exit 0: files lists each path, read-file prints one file, cost.usd is what it spent and cap_usd its cap
```

`cost.usd` is null while the cost is unknown: never report it as $0. Tell the person the outcome and give them the run's `console_url`.

### 5. Raise a cap or approve a call

A run stopped at its spend cap, or waiting for a tool call to be approved, exits 8 with `pending.kind` `budget` or `approval` in run.json.

A cap too small for the task stops the run before a request it cannot pay for. With `--cap-mode strict` no request is sent that the cap cannot cover; under the default, `expected`, a request that misses the cache can go over by at most the run's `cost.overshoot_bound_usd`:

```sh
agentrun runs start notes --max-cost-usd 0.05 --cap-mode strict --body '{"input": {"content": "Write moon.md with everything known about the Moon."}}' --wait > run.json
# exit 8 once it stops at its cap: run.json has pending.kind budget, with cap_usd, spent_usd and suggested_cap_usd; 0 if the cap was enough
```

Only the person who set the cap raises it: ask them for the new cap (`pending.suggested_cap_usd` is one that lets it go on). Then the run goes on from where it stopped:

```sh
run=$(node -p 'require("./run.json").run_id')
agentrun runs raise-cap "$run" --max-cost-usd 1
agentrun runs wait "$run" > run.json
# exit 0 completed, as in recipe 2
```

A tool call waiting for approval (`pending.kind` `approval`) is answered by the person in the console (the run's `console_url`): the server takes that answer only from their own session there, never from a token, so the CLI has no command for it. Tell them, then `agentrun runs wait "$run"` once they have.

## Exit codes

- 0: done; for `runs wait` and `runs start --wait`, the run completed.
- 1: the server refused (its error JSON on stderr); for a wait, the run failed or was cancelled, or `--timeout` passed.
- 2: bad usage, nothing sent: a bad flag or argument, or a base URL that is not http or https or has a query, a fragment, a user or a password.
- 3: the server cannot be reached.
- 4: no token, the token was refused, or the config file, the local server's record or its token file was refused (open to others, or not what it should hold).
- 8: the run waits on a person: a question, its spend cap, a stopped turn, or a paused workflow. stderr says what to run next.

## Commands

- `agentrun agents`: archive, create, forget-sign-in, get, list, runs, unarchive, update
- `agentrun files`: create, delete, get, list, upload
- `agentrun home`: delete, list, read, write
- `agentrun learning`: get, log, notes, read, retire, write
- `agentrun login`: Check a server's token, read from stdin, and keep it with the server's address in the config file
- `agentrun logout`: Remove the config file login wrote, its address and token
- `agentrun mcp-servers`: delete, get, list, oauth-client, oauth-start, preview, refresh, save
- `agentrun revisions`: list, set-current
- `agentrun runs`: archive, cancel, files, get, graph, learning, learning-diff, list, message, pause, raise-cap, read-file, resume, start, stop, timeline, unarchive, wait
- `agentrun server`: capabilities, health, mcp, openapi
- `agentrun skill`: install
- `agentrun stats`: Counts and cost over every agent and run
- `agentrun tool-keys`: delete, list, save, set
- `agentrun tool-settings`: get, save
- `agentrun triggers`: create, delete, fire, firings, get, list, rotate-secret, update
- `agentrun usage`: Usage by meter over a period
- `agentrun webhook`: delete, deliveries, get, redeliver, save, test
- `agentrun workflows`: validate
- `agentrun api METHOD PATH [--body JSON|@FILE|-]`: any route, PATH under the base URL