CLI Reference

Every agentty subcommand and flag.

view .md
for v0.9.57 · unchanged since v0.9.55
on this page
  1. The five commands most people use
  2. Subcommands
  3. Global flags
  4. agentty run
  5. Command palette and slash names
  6. Air-gap flags
  7. agentty paste

This page lists every agentty subcommand and flag. Start with the five commands below. The tables after them are the full reference.

The five commands most people use

bash
agentty                                # start in the current folder
agentty -m claude-opus-4-5             # pick a model
agentty --provider openai -m gpt-4o    # use another backend
agentty run "add a --dry-run flag"     # one prompt, answer on stdout, no UI
agentty login                          # sign in (works over SSH)
agentty --sandbox off                  # turn off the OS sandbox for bash

More examples:

bash
agentty -w ~/code/project              # work in another folder
agentty --provider kimi                # sign in with Kimi (no API key)
agentty --provider deepseek -m deepseek-v4-pro   # DeepSeek (DEEPSEEK_API_KEY)
agentty --provider ollama              # local model, no key, no cloud
agentty -k sk-ant-…                    # key for this session only, never saved
agentty --sandbox on                   # refuse to run bash without a sandbox

Subcommands

Command What it does
agentty Start an interactive thread in the workspace.
agentty login Sign in without the UI. Works over SSH.
agentty logout Delete saved credentials.
agentty status Show which auth source agentty will use.
agentty run [prompt] Run one prompt with tools and print only the answer. For scripts and CI. See below.
agentty airgap user@host Run the agent on a remote host through an SSH SOCKS tunnel. See Air-gap flags.
agentty acp Run headless as an Agent Client Protocol agent for Zed (JSON-RPC over stdio).
agentty sessions List Codex and Claude Code sessions agentty can continue, newest first. --dump N shows how session N reads as an agentty thread. Open them with Ctrl+J. See Coming from Codex or Claude Code.
agentty paste … Clipboard tools. See agentty paste.
agentty mcp-serve Serve agentty's native tools over MCP (stdio). Point any MCP client at it.
agentty mcp-login <server> [--metadata <url>] [--client-id <id>] Authorize an OAuth-gated MCP server from mcp.json (OAuth 2.1 + PKCE in your browser). --metadata and --client-id override discovery.
agentty mcp-logout <server> Delete a stored MCP server token.
agentty mcp-status List configured MCP servers and whether each is authorized.
agentty mcp import [--from junie|claude|cursor|vscode|codex] Copy another tool's MCP servers into ~/.agentty/mcp.json. With no --from, list what each tool offers. --dry-run (or -n) shows the change; --force replaces a server agentty already has. See MCP.
agentty plugin add|list|remove|approve Manage plugins. A plugin is an MCP server in any language. Example: agentty plugin add today --python today.py. Other sources: --uvx pkg, --npx pkg, --http <url>, -- cmd args. --project targets the repo config. Plugins never run until you approve them.
agentty skill add|list|remove|approve Manage installed Agent Skills.
agentty skills List discovered Agent Skills with spec-lint warnings. Exits 1 on warnings, so CI can use it.
agentty hooks [list] Show configured lifecycle hooks and whether they are approved.
agentty hooks approve Inspect and approve the active hooks file. Hooks never run unapproved; any change needs approval again.
agentty diagnostics Write a redacted bug-report bundle (build info, provider, log tail) to ~/.agentty/logs/agentty-diagnostics.txt. See Logging.
agentty config Show every folder agentty reads or writes, where it is, and its size. agentty config <name> (e.g. threads, mcp) shows one. See Storage.
agentty config env Show every storage variable and its value.
agentty config move <dir> <path> Move a folder's data, then print the export line to add. It refuses while agentty runs and checks the copy. default moves it back.
agentty config doctor Check that folders are usable, secrets are private, and storage variables are valid. Exits 1 if something needs fixing.
agentty config clean [--yes] List files that older versions left behind. --yes deletes them.
agentty rag-bench [dir] Benchmark search_docs retrieval on your own files: recall@k, MRR and nDCG per pipeline stage. Uses the auto-found docs folder unless you pass a directory.
agentty rag-eval <cases.json> Run a judged evaluation of search_code against your cases file.
agentty update [--check] Update agentty to the latest release. --check only reports whether an update exists.
agentty version, --version, -V Print agentty <version> and exit.
agentty help, --help, -h Print usage and exit.

Global flags

These match agentty --help, which prints:

output from v0.9.56, captured at build
agentty --help
agentty 0.9.56

usage: agentty [subcommand] [options]

subcommands
  login             Authenticate (API key, or OAuth via claude.ai)
  logout            Remove saved credentials
  status            Show current auth status
  airgap            Launch agentty on an air-gapped host via SSH tunnel
                    (`agentty airgap --help` for details)
  acp               Run as an ACP agent over stdio (for Zed et al.)
  paste [cmd]       Clipboard tools (richpaste). `paste setup` once on your
                    laptop makes Ctrl+V images work over ssh; `paste` prints the
                    clipboard, `paste doctor` explains the route, `paste config`
                    lists and sets the paste settings, `paste help` lists the
                    rest
  run [PROMPT]      Headless one-shot: run PROMPT through the full agent loop
                    (tools, sandbox) and print only the answer to stdout. PROMPT
                    `-` or absent reads stdin: `git diff | agentty run "review
                    this"`. Flags: --agent TYPE (general, explorer, reviewer,
                    tester, coder), --json, -o FILE, --max-turns N, --timeout
                    5m, --effort LEVEL, --read-only, --no-network, --save, --
                    resume ID|last, --events jsonl (tools, reasoning, text on
                    stderr), -v. Exit 0 ok, 1 failed or out of turns, 2 bad
                    usage, 3 provider/auth, 4 no such thread, 5 context full,
                    124 timeout, 130 Ctrl-C.
  mcp-serve         Serve agentty's native tools over MCP (stdio). Point any MCP
                    client at `agentty mcp-serve`.
  mcp import        Copy another tool's MCP servers into ~/.agentty/mcp.json (`-
                    from junie|claude|cursor|vscode|codex`, `--dry-run`). No
                    args lists what each tool offers.
  mcp-login <srv>   Authorize an OAuth-gated MCP server from mcp.json (2026-07-
                    28 OAuth 2.1 + PKCE via your browser).
  mcp-logout <srv>  Remove a stored MCP server token.
  mcp-status        List MCP servers and their authorization state.
  diagnostics       Collect a redacted diagnostic bundle for a bug report (build
                    info, logs, config — no secrets)
  skills            List discovered skills with spec-lint diagnostics (exit 1 on
                    warnings — CI-friendly validate)
  config [what]     Every folder agentty reads or writes, where it is and how
                    big. `config <name>` for one, `config env` for the storage
                    variables
  config move       `config move <dir> <path>`: move a folder's data safely,
                    then print the export line to add
  config doctor     Check storage permissions and variables
  config clean      List files old versions left behind (--yes deletes)
  hooks [list]      Show configured lifecycle hooks + approval state
  hooks approve     Inspect + approve the active hooks file (hooks NEVER run
                    unapproved; any change re-gates)
  plugin <verb>     Manage plugins (add | list | remove | approve) — a plugin IS
                    an MCP server, any language, one mcp.json entry: `agentty
                    plugin add today --python today.py`, `--uvx pkg`, `--npx
                    pkg`, `--http <url>`, or `-- cmd args`; add --project for
                    the repo config (approve it with `plugin approve <name> --
                    project`). Docs: /docs/plugins
  rag-bench [dir]   Benchmark search_docs retrieval on your own corpus (recall@k
                    / MRR / nDCG per pipeline stage)
  update            Update agentty to the latest release (--check: only report,
                    don't install)
  version           Print the agentty version and exit
  help              Show this message

options
  -k, --key KEY        API-key override for this session
  -m, --model ID       Model id (e.g. claude-opus-4-5)
  -w, --workspace DIR  Sandbox filesystem tools to this directory (default:
                       cwd). Tools refuse paths outside it. Pass `--workspace /`
                       to disable the gate.
      --sandbox MODE   Wrap bash/diagnostics in an OS-native sandbox (claybin;
                       macOS falls back to sandbox-exec). MODE = auto (default:
                       use if available), on (require backend; fail otherwise),
                       off (disable wrapping).
      --sandbox-backend B
                       Sandbox implementation: claybin (the default and only
                       engine on Linux and Windows; Linux adds seccomp +
                       landlock + cgroup2, macOS uses seatbelt + rlimits). On
                       macOS a host that cannot run claybin falls back to
                       sandbox-exec (one fixed profile), which ignores most
                       Sandbox settings. `bwrap` is accepted and runs claybin.
      --log-file PATH  Write the diagnostic log here instead of
                       ~/.agentty/logs/agentty.log (or $AGENTTY_LOGS_DIR, to
                       move just the logs off the config disk). What gets
                       captured is AGENTTY_LOG (default: warnings and errors) —
                       e.g. AGENTTY_LOG=debug, or AGENTTY_LOG=wire=trace for raw
                       HTTP bytes.
      --events jsonl   Headless `run`: one JSON object per line on stderr:
                       `turn` at each model turn, `reasoning` and `text` as the
                       model writes them, `tool` per tool call (tool, ms, ok,
                       err, args_sha). stdout keeps the answer, so both can be
                       captured.
  -p, --profile MODE   ACP permission tier (Zed shows the prompts): ask
                       (default: prompt write/exec/net), minimal (also prompt
                       reads), write (never prompt reads).
      --provider P     LLM backend. anthropic (default, OAuth/Pro/Max) or an
                       OpenAI-compatible one: openai | codex | groq | openrouter
                       | together | cerebras | deepseek | xai | mistral | gemini
                       | fireworks | ollama | llama.cpp, or a raw host[:port]
                       for any other OpenAI-compatible server. Reads
                       OPENAI_API_KEY (or the provider-specific *_API_KEY) / -k
                       for the key; local backends need no key. Persisted like -
                       m. (Switch live in-app with Ctrl-P — the picker has a
                       "Custom host…" entry too.) chatgpt talks to ChatGPT
                       natively via the reverse-engineered OAuth login (`agentty
                       login` → ChatGPT); no Codex binary is needed. copilot and
                       kimi sign in the same way via their device-flow OAuth
                       (`agentty login` → GitHub Copilot / Kimi) — no API key
                       needed. Note: hosted Claude output is watermarked per the
                       EU AI Act (invisible, no opt-out, set server-side).
                       Local/open-weight backends (ollama, llama.cpp) carry no
                       provider watermark.
  -V, --version        Print the agentty version and exit.
      --auth-header N  Auth header NAME for OpenAI-compatible backends whose
                       gateway doesn't accept `Authorization: Bearer` (e.g. X-
                       API-Key). The key (-k / OPENAI_API_KEY) is sent raw under
                       that name. Session-scoped like -k; default: Bearer.
  -h, --help           Show this message.
Flag Effect
-m, --model <id> Model id for the session, e.g. claude-opus-4-5. Saved for next time.
--provider <p> LLM backend. anthropic is the default. Other choices are OpenAI-compatible: openai · chatgpt · codex · copilot · kimi · deepseek · gemini · xai · mistral · groq · openrouter · together · cerebras · fireworks · ollama · llama.cpp. You can also pass a raw host:port, or a full URL https://host/path for a server with a path prefix. Saved like -m. Switch live with ^P. See Providers & Models.
-k, --key <key> API key for this session only. Never written to disk.
--auth-header <name> For OpenAI-compatible gateways that don't accept Authorization: Bearer (e.g. X-API-Key). The key from -k or OPENAI_API_KEY is sent raw under this header name. This session only. Default: Bearer.
-w, --workspace <dir> Limit file tools to this folder (default: the current folder). Tools refuse paths outside it. --workspace / turns the limit off.
--sandbox <mode> Run bash and diagnostics inside an OS sandbox (claybin; macOS falls back to sandbox-exec). auto (default) uses it if available. on refuses to run without it. off turns it off.
--sandbox-backend <b> Sandbox engine. Only claybin is accepted; bwrap is kept as an alias and runs claybin.
-p, --profile <mode> ACP permission tier (Zed shows the prompts). ask (default) prompts for write, exec and network. minimal also prompts for reads. write never prompts.
--lang <code> UI language for this run. Beats ui.lang in settings.json and the LC_ALL / LC_MESSAGES / LANGUAGE / LANG variables. Falls back to English.
--log-file <path> Write the diagnostic log here instead of ~/.agentty/logs/agentty.log (or $AGENTTY_LOGS_DIR). AGENTTY_LOG sets what gets logged (default: warnings and errors), e.g. AGENTTY_LOG=debug or AGENTTY_LOG=wire=trace. See Logging.
--events jsonl agentty run only. Streams events to stderr. See Events.
-V, --version Print the agentty version and exit.
-h, --help Print usage and exit.

agentty run

agentty run sends one prompt through the full agent loop (tools, sandbox, no UI) and prints the answer to stdout. Errors go to stderr, so you can capture stdout safely. If a run fails, the last stderr line is agentty run: <status>: <reason>.

bash
agentty run "add a --dry-run flag to the cli"
git diff | agentty run "review this"          # piped input is added to the prompt
agentty run --agent reviewer -o review.md "review src/"
agentty run --json --timeout 10m --max-turns 40 "fix the failing test"
agentty run --read-only --no-network "review this repo for secrets"   # safe on untrusted code
agentty run --save "plan the migration" && agentty run --resume last "now do step 1"

With no prompt, or with -, the prompt is read from stdin.

Flag Effect
--agent <type> Role: general (default), explorer, reviewer, tester, coder, or one of your own subagents.
--json Print one JSON object: status, result, error, model, turns, tool_calls, tool_errors, usage (tokens, plus last_input_tokens and context_window), duration_ms.
-o, --output <file> Write the answer (or the JSON) to a file instead of stdout.
--max-turns <n> Stop after n model turns. Default 80, or 32 for read-only roles.
--timeout <d> Stop after 90, 90s, 5m or 1h. Default 15m. A running tool is killed when time is up.
--effort <level> Let the model think: low, medium, high, xhigh, max or auto. Clamped to what the model supports. Off by default.
--read-only Only tools that read. Writes, commands and network tools are hidden from the model and refused if it asks anyway.
--no-network Commands run with no network (an empty network namespace), and network tools are refused. Needs the claybin sandbox; without it the run won't start.
--save Save the conversation as a thread. The id is in --json output and in -v.
--resume <id|last> Continue a saved thread with a new prompt. last is the newest. The result is saved back to the same thread.
-v, --verbose Print stats on stderr at the end, including how full the context window got.
--events jsonl One JSON line per event on stderr. See Events.

Ctrl-C or SIGTERM stops the run and kills the running tool. A second Ctrl-C exits at once.

Events

With --events jsonl, stderr gets one JSON object per line during the run. stdout still gets only the answer.

json
{"ev":"turn","turn":1,"seq":0}
{"ev":"reasoning","turn":1,"text":"the test fails because…","seq":1}
{"ev":"tool","tool":"read","ms":3,"ok":true,"args_sha":"1a2b3c4d","seq":2}
{"ev":"text","turn":2,"text":"Fixed it by…","seq":3}
  • turn marks each model turn. text and reasoning carry what the model writes. tool is one line per tool call.
  • args_sha is a hash of the arguments, not the arguments. Use it to tell whether two calls were identical.
  • reasoning appears when the provider streams the model's thinking. Models that reason on their own (deepseek-r1 and similar, which send reasoning_content) show it without a flag. For Claude, add --effort so it thinks at all.
  • Text is sent one paragraph at a time. Join the lines of one kind, in order, to get the whole text.
bash
agentty run --effort high --events jsonl "fix the flaky test" 2> events.jsonl
jq -r 'select(.ev=="reasoning") | .text' events.jsonl

Exit codes

Exit code Meaning
0 Finished with an answer.
1 The agent failed or ran out of turns. Any partial answer is still printed.
2 Bad usage (unknown flag, bad value, no prompt).
3 Provider or auth problem. Also a rate limit the provider says lasts more than 15 minutes (a daily or plan quota); that ends the run at once. Shorter rate limits are retried up to 3 times, at most 30 s apart.
4 --resume found no such thread.
5 The model's context window filled up. stderr says how big the window was and how big the last prompt got.
124 Hit --timeout.
130 / 143 Stopped by Ctrl-C / SIGTERM.

Command palette and slash names

Type / at the start of the composer to get a menu of everything you can run by name: built-in actions (/new, /compact, /model, /rename, /fork, /rewind, /review, /threads, /settings, /tools, /login, /quit), your own commands, skills and MCP prompts. See Slash Commands.

^K opens the fuzzy command palette with every action:

Command What it does
New thread Start a fresh conversation.
Compact context Replace the history with a structured summary to free up the context window. It runs on the cheapest capable model of the active provider, so it costs a fraction of a normal turn.
Compaction depth Set how full the context window gets before agentty compacts in the background: 75% Aggressive → 90% Balanced → 95% Deep. Higher values help on a 1M-context model (see Providers). Kept across restarts.
Review changes Open the diff review pane (also ^R).
Accept all / Reject all changes Apply or discard every pending hunk.
Rewind to checkpoint Go back to an earlier turn's worktree snapshot through a diff-preview picker. Needs a git repo and an idle session. See Checkpoints.
Cycle profile Write → Ask → Minimal (also S-Tab).
Open model picker / Switch provider Change the model (^/) or the backend (^P).
Open threads / Open plan Browse saved conversations (^J) or view the todo plan (^T).
Run code block Run a fenced block from the last reply (^G).
Login / Quit Sign in, or exit agentty.

Air-gap flags

Flags for agentty airgap:

output from v0.9.56, captured at build
agentty airgap --help
usage: agentty airgap [--setup] [--clipboard-relay] [--remote-agentty PATH] <user@host>
       agentty airgap [--setup] <user@host> --acp [acp flags…]

  Opens an SSH session to <user@host> with `-R 1080`, which makes
  OpenSSH expose a SOCKS5 proxy on the remote's localhost:1080.
  Connections to it are tunnelled back through SSH and dialed by
  this laptop, so the remote agentty — pointed at the proxy via
  AGENTTY_SOCKS_PROXY — can reach every destination it needs (chat,
  OAuth refresh, web tools) over a single tunnel.  TLS / cert
  verification stay pinned on the real upstream end-to-end, so
  the network path between laptop and remote can't MITM you.

  Trust boundary (read this before --setup): the remote ends up
  with a copy of ~/.agentty/credentials/credentials.json, which contains
  your OAuth refresh token (or API key). A compromised remote
  can therefore exfiltrate your Anthropic credentials independent
  of the tunnel. agentty airgap protects the *network* between
  laptop and remote, not the remote itself — treat the remote as
  a credential-bearing peer, not a sandboxed proxy.

  --setup            Copy ~/.agentty/credentials/credentials.json from
                     this laptop to the remote (chmod 600) before
                     launching.  Run this once on first connect or
                     after re-OAuthing locally.
  --remote-agentty PATH Absolute path to agentty on the remote.  Default:
                     `agentty` (resolved via remote PATH).
  --acp [acp flags…] Don't launch the TUI — instead print a ready-to-
                     paste Zed `agent_servers` config that runs the
                     remote `agentty acp` over this same SSH+SOCKS
                     tunnel, with Zed owning the process. Everything
                     after --acp is forwarded to the remote acp agent
                     (e.g. --acp -m claude-haiku-4-5 --profile ask).
                     Must come AFTER <user@host>.
  --clipboard-relay  Make Ctrl+V paste images and files on the remote.
                     Starts the clipboard agent here and forwards a
                     socket to it, so the remote reads THIS machine's
                     clipboard. Not needed if you ran `agentty paste
                     setup` here: then every ssh session carries it.

  ssh and scp must be on this laptop's PATH.  Pass extra ssh args
  via the AGENTTY_AIRGAP_SSH env var (e.g. -i, -p, -J).

  Without a relay, paste still works for text, and for images in
  terminals that share the clipboard (kitty). `agentty paste doctor`
  on the remote shows which route a paste takes.
Flag Effect
--setup Copy credentials to the remote on the first run.
--acp Print a ready-to-paste Zed agent_servers config that tunnels agentty acp over ssh stdio. Flags after it go to the remote agent. See Zed / ACP.
--clipboard-relay Forward this machine's clipboard agent for this session, so Ctrl+V on the remote pastes images and files. Not needed after agentty paste setup.
--remote-agentty <path> Path to agentty on the remote, if it isn't on PATH.

agentty paste

The clipboard commands. Ctrl+V in the composer uses the same reader and settings. Full guide: Clipboard & Images.

Command What it does
agentty paste [-o DIR] Print text, or save images and files (into DIR, else the save folder) and print their paths. Works locally and over ssh. Exits 1 when nothing could be read.
agentty paste doctor Show the settings in effect, state folder, agent, display, ssh, forwarded sockets, and the result of a real paste. Exits 1 if that paste fails.
agentty paste setup Run once on the machine you type on. Adds (or updates) the ssh hook block at the top of ~/.ssh/config and starts the agent, so Ctrl+V over ssh reads that machine's clipboard.
agentty paste agent Run the clipboard agent in the foreground (setup starts it in the background).
agentty paste config [get|set|reset] The paste settings: config set <key> <value>, config get <key>, config reset <key|all>. Same rows as Settings → Paste. See Configuration → Paste.
agentty paste howto One-time macOS and Windows snippets that turn the clipboard into a richpaste:1: line, for terminals that never pass the clipboard on.
agentty paste page Print the web page that does the same in any browser (also at agentty.org/paste).
agentty paste encode FILE Print FILE as one richpaste:1: line.
agentty paste decode [DIR] Read such lines on stdin and save the files they carry.
agentty paste help List all paste commands.