CLI reference
Every astracode-agent subcommand and flag, environment variable, file, JSON shape and exit code.
On this page
Synopsis
astracode-agent --help
astracode-agent ["<first request>"] a conversation in this folder
astracode-agent --continue | --resume pick up an earlier one
astracode-agent -p "<prompt>" [options] one task, then exit
astracode-agent login [--no-browser] [--code]
astracode-agent logout
astracode-agent status
astracode-agent update
astracode-agent undo [<run>] [--list] [--restore <id>] [--cwd <dir>]
astracode-agent review [--base <ref>] [--output-format text|json] [--max-steps <n>] [--cwd <dir>] [--trust] [-v]
astracode-agent acp [--agents <json|file>] [--agent <name>] [--allow-agent-mcp] [--trust]
astracode-agent plugin <verb> ...
astracode-agent --version | --help
Unknown options are refused: the CLI prints astracode-agent: and the problem, then the usage, and exits 2. An unexpected error prints its message and (set ASTRACODE_DEBUG=1 for the details), and exits 1.
Subcommands
| Command | What it does | Exit codes |
|---|---|---|
| (none) | A conversation: full screen at a terminal, the line session otherwise. Takes an optional first request, -c/--continue, -r/--resume, --cwd, --agents, --agent, --trust, -v. The -p-only options are refused: --X applies to -p runs. See The conversation. | 0 on leaving; 1 when the first run was not finished; 2 when it cannot open |
-p, --print | One task. See Scripts and CI. | 0, 1, 2, 130 |
login | Sign in through the browser. --no-browser prints the link without opening a browser; the link only works on this machine. --code signs in with a code pasted from a browser anywhere, and is used automatically when SSH_CONNECTION or SSH_TTY is set. See Sign in. | 0 signed in; 1 failed; 130 cancelled |
logout | Removes the saved session. | 0 |
status | Who you are signed in as, or that the API key is in use. May renew the session. | 0 signed in; 1 not |
update | Installs the latest version (install script), or prints the Homebrew or npm command. | 0, 1, or the installer's code |
undo | Puts back a run's changes. --list shows ten runs, <run> picks one, --restore <id> takes an undo back, --cwd picks the folder. A run with --list or --restore, or both of those, is a usage error. | 0, 1 |
review | Reviews the branch. See Reviewing a branch. | 0, 1, 2, 130 |
acp | Serves the Agent Client Protocol on stdin and stdout. See Zed and JetBrains. | |
plugin | Manages plugins. See Plugins. | 0 done; 1 refused or failed; 2 usage |
There is no mcp subcommand: MCP servers go in the settings file, and /mcp lists them in a conversation.
Options for -p
| Option | Default | Also on |
|---|---|---|
--mode agent|plan | agent | |
--output-format text|json|stream-json | text | review (text or json) |
--permissions read-only|auto|full | read-only | |
--max-steps <n> | 150 (60 for review) | review |
--cwd <dir> | the current folder | conversation, review, undo |
--agents <json or file> | conversation, acp | |
--agent <name> | conversation, acp | |
--allow-agent-mcp | off | acp |
--report-to <url> | ||
--trust | no effect with -p | conversation, acp, review |
-v, --verbose | off | conversation, review |
--agents takes JSON, or a file holding it, in Claude Code's shape: {"<name>": {"description": "...", "prompt": "...", "tools": [...], "model": "fast"}}. model is a tier: inherit, fast or strong. Errors (exit 2) say what is wrong: neither JSON nor a readable file, not an object of agents, a bad name, a missing description or prompt, or for --agent a name that does not exist, with the list of agents.
Environment variables
| Variable | Effect |
|---|---|
ASTRACODE_API_KEY | An ac_live_ key from your dashboard. Used instead of a saved session by -p, review, acp and status; the conversation asks once per key. |
ASTRACODE_GATEWAY_URL | The gateway to use. Default https://api.astracode.io. |
ASTRACODE_TRUST | Exactly 1 trusts the folder, as --trust does. |
ASTRACODE_CONFIG_DIR | The config folder. Setting it also keeps the session in a file there instead of the macOS Keychain. |
XDG_CONFIG_HOME | The base of the config folder when ASTRACODE_CONFIG_DIR is not set. |
ASTRACODE_THEME | Force a theme: dark, light, dark-cb, light-cb, dark-ansi or light-ansi. |
NO_COLOR, FORCE_COLOR, COLORTERM, TERM, COLORFGBG | Colour detection, as usual. |
ASTRACODE_NO_ANIMATION | Turn off the spinner and animation. |
ASTRACODE_DEBUG | Print the full details of an unexpected error. |
ASTRACODE_UPDATE_CHECK | 0 turns the update check off; 1 checks even when stderr is not a terminal or CI is set. |
CI | Set: no update check, and requests are marked as coming from CI. |
SSH_CONNECTION, SSH_TTY | Set: login signs in with a pasted code. |
ASTRACODE_DOWNLOAD_BASE | Where the installer and update download from. Default https://astracode.io/downloads/cli. |
ASTRACODE_INSTALL_URL | The installer update runs. |
ASTRACODE_NPM_REGISTRY | The registry the update check asks, for an npm install. |
ASTRACODE_VERSION | Installer: the version to install. |
ASTRACODE_BIN_DIR | Installer: where the command goes. Default ~/.local/bin, or %USERPROFILE%\.local\bin on Windows. |
ASTRACODE_DATA_DIR | Install script: where versions are kept. Default ~/.local/share/astracode-agent. |
ASTRACODE_PLUGINS_DIR | Where plugins are kept. Default ~/.astracode/plugins. |
ASTRACODE_GIT | The git program used to fetch plugins. |
VISUAL, EDITOR | The editor Ctrl-G opens. |
SHELL | The shell ! runs in. |
PATH | Where rg and git are found. |
Files
The config folder is $ASTRACODE_CONFIG_DIR, else $XDG_CONFIG_HOME/astracode, else ~/.config/astracode, on every system: on Windows that is %USERPROFILE%\.config\astracode. It is private to you.
| File | What it holds |
|---|---|
settings.json | Your settings: mcp.servers, theme, trustedFolders, onboarded, apiKeyChoice, and any other AstraCode setting the agent reads, with or without the astracode. prefix. Never read from a project. |
credentials.json | The session, readable only by you, on Linux and Windows, or anywhere ASTRACODE_CONFIG_DIR is set. On macOS otherwise the session is in the Keychain as AstraCode CLI. |
secrets.json | Sensitive plugin options, where there is no Keychain. On macOS they are in the Keychain as AstraCode CLI secrets. |
update-check.json | When the update check last ran (checked at most daily). |
agent-mcp.json | Your answers about agent files' MCP servers. |
history/ | What you typed, per folder, for Up and Ctrl-R. |
sessions/ | Saved conversations, per folder. |
checkpoints/ | Each folder's checkpoints, for undo and /rewind. |
| Elsewhere | What it holds |
|---|---|
~/.astracode/memories | Memories, shared with the editor. |
~/.astracode/plugins | Installed plugins, shared with the editor. |
.astracode/agents, .claude/agents, ~/.astracode/agents, ~/.claude/agents | Agent definitions, nearest first. |
.astracode/skills, .astracode/commands, .astracode/hooks.json and the other folders | As in the editor; see Skills and commands and Hooks. |
JSON shapes
| Command | Shape |
|---|---|
-p --output-format json | {type, ok, end, summary, filesChanged[{path, created, added, removed}], denied[{description, warning?}], steps, planSlug, durationMs, tasks[], runId?}; on an early failure {type, ok: false, error}. Fields: Scripts and CI. |
-p --output-format stream-json | One agent event per line, then {type: "denied", ...} for each refusal and the final result. |
review --output-format json | {type, ok, end?, base?, files[], findings[{file, line, summary, failure, severity, category?}], reported, truncated, summary?, error?, steps?}. Fields: Reviewing a branch. |
plugin list --json | The installed plugins, or with --available the marketplaces' listings. |
--report-to events | POST <url>/events with {seq, type, data}, type started, step, tool, report or ended. |
Exit codes
| Code | -p | review | Others |
|---|---|---|---|
| 0 | Finished | Finished (with or without findings) | Done |
| 1 | Not finished, or the gateway refused | Not finished, no findings reported, or the gateway refused | status not signed in; login failed; undo nothing to undo or failed; plugin refused; conversation first run not finished |
| 2 | Usage error, not signed in, bad --cwd, bad --agents or --agent, empty stdin prompt | Not in a git repository, no common ancestor, no base found, usage error, not signed in | Usage errors |
| 130 | Interrupted | Interrupted | login cancelled |
← Zed and JetBrains Usage and limits →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems