CLI Reference
Every agentty subcommand and flag.
on this page
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
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 bashMore examples:
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 sandboxSubcommands
| 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:
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>.
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.
{"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}turnmarks each model turn.textandreasoningcarry what the model writes.toolis one line per tool call.args_shais a hash of the arguments, not the arguments. Use it to tell whether two calls were identical.reasoningappears when the provider streams the model's thinking. Models that reason on their own (deepseek-r1 and similar, which sendreasoning_content) show it without a flag. For Claude, add--effortso 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.
agentty run --effort high --events jsonl "fix the flaky test" 2> events.jsonl
jq -r 'select(.ev=="reasoning") | .text' events.jsonlExit 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:
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. |