Docs › CLI

AstraCode CLI

Install astracode-agent, sign in, and use the AstraCode agent in a terminal, a CI job, or Zed and JetBrains.

astracode-agent is the AstraCode agent without the editor. On its own it opens a conversation in the current folder. With -p it runs one task and exits, for scripts and CI. It runs the same agent as the editor, with AstraOne's model routing and the same approval rules, on the same account.

The command is astracode-agent because astracode already opens the editor.

Install

On macOS or Linux, arm64 or x64:

curl -fsSL https://astracode.io/install | sh

It puts a standalone binary in ~/.local/bin with Node built in. It checks the download's checksum, and on a Mac that AstraCode signed it. Nothing needs sudo.

Or, with Homebrew:

brew install astracode-io/tap/astracode-agent

Or, with Node 20 or later:

npm install -g astracode-agent

The CLI tells you when a newer version is out. If you used the installer, astracode-agent update installs it. A Homebrew or npm copy is theirs to update, and the CLI names the command: brew upgrade astracode-agent or npm install -g astracode-agent@latest.

Sign in

• On your own machine, run astracode-agent login once. It signs you in through your browser and keeps the session, in the Keychain on macOS and in ~/.config/astracode elsewhere. Using it at least every day and a half keeps it signed in.
• Over SSH, astracode-agent login --no-browser prints the link to open on another machine instead.
• In CI, or anywhere nobody can sign in, create an API key on your dashboard and set ASTRACODE_API_KEY. A key takes precedence over a saved session, can carry its own limit, and can be revoked without signing anyone out.
• astracode-agent status says who you are signed in as, and exits 1 when nobody is. astracode-agent logout forgets the session.

The first time you run it, it checks it can reach AstraCode, asks which colour theme suits your terminal, signs you in, and asks once per folder whether you trust what is in it.

A conversation

astracode-agent
astracode-agent "why does the login test fail?"
astracode-agent --continue    # this folder's last conversation
astracode-agent --resume      # choose an earlier one

• Before it acts, it asks. Approve an edit or a command once, for the rest of the session, or say no and tell it what to do instead.
• Shift-Tab cycles three modes: ask, auto, where edits and commands run and only risky ones ask, and plan, where it reads, writes a plan and offers to build it.
• Esc stops a run and keeps what it has done. A message typed while it works reaches it at its next step.
• Every edit is shown as a diff. Ctrl-O shows a tool's full output and Ctrl-T the todo list. The footer shows the mode, the model and how much of the context is used.
• \ then Enter, Ctrl-J or Option-Enter starts a new line. Up and Down go through history and Ctrl-R searches it. Ctrl-G opens the message in $EDITOR, and Ctrl-V pastes an image on macOS.
• @ mentions a file. !command runs in your shell and sends its output with your next message. # note remembers something about the project.

Your own commands and skills from .astracode/commands and .astracode/skills appear in the / menu. MCP servers go under mcp.servers in ~/.config/astracode/settings.json. That file is read from your home directory only, never from the project: mcp.servers names commands that run on start, and a settings file inside a repository you cloned could otherwise run anything.

One task, from a script or CI

astracode-agent -p "fix the failing test in tests/test_billing.py" --permissions auto

Nobody is there to approve anything, so this is decided up front:

• read-only (the default): it reads, searches and answers, and is refused every edit and every command.
• auto: it edits files and runs commands, but is still refused a command the risk check flags, such as git push or rm -rf outside the project, a request to another machine, and saving a memory.
• full: those are allowed too.

Every refused action is listed in the result, so a CI log says why nothing changed. With --output-format json the result is one object with ok, end, summary, filesChanged, denied, steps and durationMs.

A run that stopped short fails the job. It does not report success with an apology in the summary.

Review a branch

astracode-agent review --base main --output-format json

Reviews this branch's changes against --base, which defaults to its upstream, then the remote's default branch, then main. It is read-only, and reports only findings it can describe a concrete failure for, at most eight. With --output-format json it prints { ok, base, files, findings, ... } for a script to act on.

In Zed or a JetBrains IDE

astracode-agent acp speaks the Agent Client Protocol, so an editor that runs external agents can use AstraCode as its agent. The editor starts it; you do not run it yourself. Sign in the same way as on the command line.

Zed: add this to settings.json, then pick AstraCode in the agent panel.

{
  "agent_servers": {
    "AstraCode": {
      "type": "custom",
      "command": "astracode-agent",
      "args": ["acp"]
    }
  }
}

JetBrains: in the AI Chat tool window choose Add Custom Agent, and put this in the ~/.jetbrains/acp.json it opens. Use the full path that which astracode-agent prints.

{
  "agent_servers": {
    "AstraCode": {
      "command": "/Users/you/.local/bin/astracode-agent",
      "args": ["acp"]
    }
  }
}

The editor shows each edit as a diff and asks before the agent changes a file or runs a command. Risky commands and requests to other machines are asked about every time.

In GitHub Actions

- run: curl -fsSL https://astracode.io/install | sh
- run: ~/.local/bin/astracode-agent -p "Fix the failing test in tests/test_billing.py" --permissions auto --output-format json
  env:
    ASTRACODE_API_KEY: ${{ secrets.ASTRACODE_API_KEY }}

Let the agent make the edits, and let the workflow's own steps commit, push and comment. The agent refuses git push under auto for exactly that reason.

What needs the editor

Language-server lookups, live diagnostics and the code index need the editor, in every way of running the CLI. MCP servers, memories and rewinding a turn are part of the conversation. Content search uses rg from your PATH, so install ripgrep; GitHub's runners already have it.

All documentation

Get started

• Quickstart
• Install AstraCode
• The chat panel

Agent

• Agent overview
• Approvals and permissions
• Plan mode
• What the agent can do
• Running commands
• Browser tools
• Checkpoints and undo
• Infrastructure as code
• Running several agents at once

Context

• How context works
• Rules
• Memories

Workspaces

• Workspaces
• Working across several repositories

Connectors

• Connectors (MCP servers)

Extending AstraCode

• Plugins and skills
• Skills
• Hooks
• Dictation

CLI

• AstraCode CLI

Reference

• Settings reference
• Keyboard shortcuts
• Models