agentrun-cli · diff

git:20261115.2227863 to git:20261115.039beb7

15 added, 1 removed. Audit A to B.

What this update changes in the checks

This update newly trips 1 check:

  • No link to a raw IP address
    matched: http://127.0.0.1

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
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).
+ description: Onboard and manage AgentRun agents from a shell. Connect existing Claude Code or Codex setups locally or remotely, import selected history, or create a new agent. Start runs, inspect results and use checked learning. Use when asked to connect, run or manage AgentRun agents from a terminal or script, or for anything the server's MCP tools do not cover (files, 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. -->
# 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.
A list command (`agentrun agents list`, `agentrun runs list` and the others with `--cursor`) prints one page, with the `next_cursor` to pass as `--cursor` for the next; `--all` reads every page and prints them as one list, its `next_cursor` null.
+ ## Choose the onboarding path
+
+ For general setup, first establish whether the user wants to start a new agent or bring an existing Claude Code/Codex setup. Ask only when intent is missing: Build an agent already chose new; Connect agent already chose existing. Reuse the named instance and read its matching `/skills/agentrun-serve/SKILL.md`; do not start a replacement. A new agent starts from a suitable template or custom definition after clarifying its job, inputs and expected result. Inspect configured models before asking for a key. Existing-agent connection and selected history import need no destination model key; live jobs use the source runtime's existing sign-in. Finish with the first requested run's result and console link, or the imported history and counts; offer self-improvement separately.
+
## 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. 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).
+
+ ## Connect agent
+
+ First clarify whether the user wants a live connection, historical import, or both; then establish the source machine, destination instance and selected project/agent/profile. Do not infer history import or learning consent from a connection request. Read the target server's matching `/skills/agentrun-serve/SKILL.md` for the complete flow.
+
+ On the machine with the existing Claude Code or Codex setup, use `npx @parcha/agentrun native discover --project /absolute/project` to inspect supported project defaults, named Claude agents and Codex profiles without a model call. Then run `npx @parcha/agentrun native connect --project /absolute/project --runtime claude-code` (or `codex`), adding `--agent NAME` or `--profile NAME` for a discovered selector. The local server uses `--data DIR`; `--url http://127.0.0.1:PORT` selects its loopback address. For another machine, use the existing Python connector's `remote` command from the same reviewed build, with the matching `agentrun-serve remote-bridge` runtime. The released observation-only connector is not a remote execution worker. Pair using the console's one-use code entered into the secure CLI prompt; never send a broad server token or put the code in a command argument. Source configuration and sign-in stay on that machine. For completed project history, preview with the matching Python connector’s `remote history-preview --project /absolute/project --runtime claude-code` (or `codex`). Select History only or Both when creating the owner’s code; the source must also explicitly pass `--history-only` or `--history` to `remote connect`. History-only starts no worker or learning and needs no native sign-in. History flags reject named-agent/profile selectors because native logs cannot attribute sessions to them reliably. Re-import the approved target with `remote import-history --state-dir /private/connector`; duplicates are skipped. Historical records never become live jobs or automatic learning. Local-store imports still use the separate maintenance-window flow in the server skill.
+
+ For an authorized live connection, open the connected agent, verify its native sign-in, and turn Self-improving On only when requested to use the existing checked/graded learning pipeline. Native projects keep their original instructions, tools, hooks, permissions and login. AgentRun adds notes and skills without rewriting those files. Native dollar caps, interactive approvals, learned workflows and attachment to an already-running desktop conversation are unavailable; never bypass native permissions to make a run work. Off supplies and creates no AgentRun learning on subsequent runs. Reflection and grading make additional model calls using native sign-in unless the server has an explicit grading model route.
+
+ For the remote development build, install the Python connector from `./connector` in the same reviewed checkout after building its Node runtime (Python 3.12+ and Node 24.22.3+). A checkout build does not put `agentrun-serve` on PATH: pass `--bridge /absolute/path/to/checkout/packages/serve/dist/native/remote-worker-bridge.js` to discovery and connection. The Python connector and Node management CLI share the name `agentrun`; verify the executable, or use `python -m agentrun_cli` inside the installed connector environment. Keep its source worker online for live jobs. Inspect accepted notes and skills in Learning Dojo, then verify a fresh run uses them; imported history never supplies that learning automatically.
## 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
```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 > 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
```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 > 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:
```sh
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
```sh
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 paused 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. No request is sent that the cap cannot cover, a cache miss included:
```sh
agentrun runs start notes --max-cost-usd 0.05 --body '{"input": {"content": "Write moon.md with everything known about the Moon."}}' --wait > out.json
# exit 8 once it pauses 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:
```sh
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).
- 5: the server does not offer the command here: a 501, `unsupported_here`, its error saying why (a capability this server has off, say).
- 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, connect-native, create, delete-agent-archil, disconnect-native, discover-native, forget-sign-in, get, get-agent-archil, get-learning-loop, get-native, list, list-learning-promotions, runs, unarchive, update, verify-native
- `agentrun connectors`: complete-remote-command, enroll-remote-connector, import-remote-history, import-remote-target, list-remote-connectors, poll-remote-connector, register-remote-connector, remote-command-events, revoke-remote-connector
- `agentrun files`: create, delete, get, list, upload
- `agentrun home`: delete, list, read, write
- `agentrun learning`: batch, batch-cancel, batch-start, batches, cost, evals, get, log, notes, read, record-eval, replay, retire, workflow-revisions, write
- `agentrun local`: create-pairing, delete-composio-subscription, delete-computer, delete-workspace-archil, disconnect-git-hub, get-git-hub-connection, get-workspace-archil, list-composio-events, list-composio-triggers, list-computer-choices, list-computers, receive-hook-composio, rotate-composio-secret, 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 Observations`: get-observations
- `agentrun revisions`: list, set-current
- `agentrun runs`: archive, cancel, computer-call, computer-release, create-inline-run, files, get, grade-run, graph, hand-back-run-computer, learning, learning-diff, list, message, pause, raise-cap, read-file, resume, start, start-held, stop, take-over-run-computer, timeline, unarchive, wait
- `agentrun sdk-runs`: complete, events, get, start
- `agentrun server`: capabilities, health, mcp, openapi
- `agentrun skill`: install
- `agentrun stats`: Counts and cost over every agent and run
- `agentrun template`: apply, delete, eval, import, install, list, validate
- `agentrun tool-keys`: list
- `agentrun tool-settings`: get, save
- `agentrun triggers`: create, delete, fire, firings, get, list, 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