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).

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 has every command with its flags and route.

The server and the token

The first of these that is set wins:

--base-url URL (the API, ending /v2), else AGENTRUN_BASE_URL, with the token in AGENTRUN_API_KEY.
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.
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:

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. Keys and other secrets are set in the console, signed in: the token can't write one, so no command does (agentrun tool-keys list names the keys and fields, and whether each is set, never a value).

Recipes

Run them in order, in one working directory: each writes out.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

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

agentrun runs start notes --max-cost-usd 5 --body '{"input": {"content": "Write notes.md with three facts about the Moon."}}' --wait > out.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

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

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

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

4. Read what it wrote and what it cost

run=$(node -p 'require("./out.json").run_id')
agentrun runs files "$run"
agentrun runs read-file "$run" region.md
agentrun runs get "$run" > out.json && node -p 'JSON.stringify(require("./out.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 out.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:

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 > out.json
# exit 8 once it stops at its cap: out.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:

run=$(node -p 'require("./out.json").run_id')
agentrun runs raise-cap "$run" --max-cost-usd 1
agentrun runs wait "$run" > out.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.

From a program

Two clients call the same API from code, with the same server and token. @parcha/agentrun-client is the TypeScript one, new AgentRun({ baseUrl, apiKey }); npm install @parcha/agentrun-client installs it. parcha-agentrun (python/) is the Python one, AgentRun(base_url=..., api_key=...) from the agentrun module; pip install parcha-agentrun installs it. Both default to AGENTRUN_BASE_URL and AGENTRUN_API_KEY and read no config file. Each command here is a method, grouped the same way: agentrun runs start is client.runs.start, and client.runs.wait and client.runs.follow do what --wait and --follow do.

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 local: connect-git-hub, delete-workspace-archil, disconnect-git-hub, get-git-hub-connection, get-workspace-archil, git-hub-callback, git-hub-installed, list-computers, receive-hook-github, test-computer, test-workspace-archil
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, private-hosts, refresh
agentrun revisions: list, set-current
agentrun runs: archive, cancel, create-inline-run, files, get, graph, hand-back-run-computer, learning, learning-diff, list, message, pause, raise-cap, read-file, resume, start, stop, take-over-run-computer, timeline, unarchive, wait
agentrun server: capabilities, health, mcp, openapi
agentrun skill: install
agentrun stats: Counts and cost over every agent and run
agentrun template: apply, eval, list, validate
agentrun tool-keys: list
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