Arcanist CLI

Command-line interface for Arcanist: create coding agent sessions, follow their output, and manage access tokens from your terminal or automation.

Install

npm install -g @tryarcanist/cli

Requires Node.js 22 or newer.

Quick start

arcanist auth login                 # paste a token from Settings > CLI Tokens
arcanist sessions create https://github.com/your-org/your-repo "fix the login bug"

export ARCANIST_TOKEN=arc_...       # write-scoped for create/send/stop
SESSION_ID=$(arcanist sessions create your-org/your-repo "add tests for the auth module" --json | jq -r .sessionId)
arcanist sessions events "$SESSION_ID" --follow --json

Authentication

Generate a CLI token in the Arcanist UI at Settings > CLI Tokens, then:

arcanist auth login
# paste your arc_... token when prompted; input is masked

Token config is stored at ~/.arcanist/config.json. Multiple active tokens per user are supported; revoke tokens independently when a device or workflow no longer needs access.

Use a read-scoped token for inspection and debugging; use a write-scoped token only to create sessions, send prompts, or stop runs.

You can also pipe the token via stdin:

printf "arc_..." | arcanist auth login --token-stdin

Auth and API URL precedence:

flag > environment > ~/.arcanist/config.json

Supported environment variables:

export ARCANIST_TOKEN=arc_...
export ARCANIST_API_URL=https://api.tryarcanist.com

--token and --api-url are available for one-off invocations. Prefer ARCANIST_TOKEN over --token for persistent use; CLI flags can appear in shell history and process lists.

Non-local API URLs must use HTTPS and must not embed credentials.

Global flags

arcanist --json
arcanist --quiet
arcanist --api-url https://api.tryarcanist.com
arcanist --token arc_...
arcanist --no-color

JSON output, errors, and exit codes

With --json, successful command output is machine-readable and newline-terminated. Errors are written to stderr as:

{
  "error": { "code": "auth", "message": "Not logged in.", "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`." }
}

Exit codes:

0   ok
1   user/input error
2   auth error (401/403)
3   not found (404)
4   conflict (409)
10  server or network error
130 interrupted

Mutation commands send an Idempotency-Key header. The CLI does not auto-retry mutation endpoints; retry explicitly with the same --idempotency-key when a request may have already reached the server. --idempotency-key is available on sessions create and sessions send.

Commands

arcanist auth login

arcanist auth login
printf "arc_..." | arcanist auth login --token-stdin
arcanist auth login --api-url https://api.tryarcanist.com

arcanist auth whoami

arcanist auth whoami
ARCANIST_TOKEN=arc_... arcanist auth whoami --json

JSON mode prints the raw /api/auth/whoami API response. Fields currently include userId, email, tokenId, tokenScope, and authMode.

arcanist sessions create <repo-url> [prompt]

Creates a new session and sends the initial prompt.

arcanist sessions create https://github.com/your-org/your-repo "fix the login bug"
arcanist sessions create your-org/your-repo "continue this work" --start-branch wip/resume-me
printf "add tests" | arcanist sessions create your-org/your-repo --prompt-stdin --json
printf "add tests" | arcanist sessions create your-org/your-repo --prompt-stdin --wait
arcanist sessions create your-org/your-repo - --model gpt-5.5
arcanist sessions create your-org/your-repo "port to claude" --backend claude_code --model claude-opus-4-8
arcanist sessions create your-org/your-repo "refactor auth" --reasoning-effort xhigh
arcanist sessions create your-org/your-repo "fix release branch" --base-branch release/2026-06
arcanist sessions create your-org/your-repo "review the trace" --uploaded-file trace.txt
arcanist sessions create your-org/your-repo "verify the deployed change" --cold
arcanist sessions create your-org/your-repo "retry-safe create" --idempotency-key 1f0e6f1a-...

--backend picks the agent runtime backend: codex (default) or claude_code. --model must be valid for the chosen backend — codex runs OpenAI models (gpt-5.4 default, gpt-5.5), claude_code runs Anthropic models (claude-opus-4-8 default, claude-sonnet-4-6) — and the CLI rejects a mismatch before any network call. claude_code sessions require an Anthropic API key configured in Settings.

--wait blocks until the created prompt finishes, prints the resulting PR/branch line in human-readable mode when it is already available, and exits non-zero if the prompt finishes with status: failed, making it suitable for cron or other schedulers that alert on command failure. JSON mode waits quietly and prints the create payload after the prompt completes successfully. --poll-interval <ms> tunes the completion check frequency.

Use --base-branch <branch> to target a non-default base branch. The CLI only validates that the branch value is non-empty; branch existence is checked later by the session runtime.

Use --start-branch <branch> to resume an existing branch with its history instead of forking a fresh branch off base; the control plane verifies the branch exists on the remote and fails closed if it does not.

Repeatable --uploaded-file <path> flags attach local UTF-8 text files to the prompt. Uploaded file names come from the local basename; directory components are not sent.

--cold is a deprecated no-op retained for backward compatibility. Sessions always start from a fresh sandbox (the warm sandbox pool was removed), so the flag has no effect.

--idempotency-key <uuid> is for manually retrying a create request that may have reached the server. The CLI derives separate session and prompt idempotency keys from the provided value.

--onboarding creates an onboarding session: the agent authors the repo's .arcanist.json, .arcanist/ runtime files, ARCANIST.md, and conditionally .arcanist/sandbox.yaml + .arcanist/sandbox.layer.Dockerfile (when the base sandbox lacks a needed toolchain), proves what it can inside its sandbox, and opens the setup PR ready for review. The onboarding behavior is driven by the bridge's canonical onboarding playbook, not the prompt, so --onboarding needs no prompt: arcanist sessions create <repo> --onboarding --wait. Any prompt supplied alongside --onboarding is ignored. Team use; not part of the external API surface.

JSON mode returns {sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, baseBranch?, startBranch?, onboarding?, promptId?}. sessionUrl is emitted only when the server returns it; agentRuntimeBackend only when --backend is passed. With --wait, JSON mode also includes best-effort result fields when available: prUrl?, publishedBranch?, and lastBranch?.

arcanist sessions send <session-id> [prompt]

Sends a follow-up message to an existing session.

arcanist sessions send abc123 "also update the tests"
arcanist sessions send abc123 "use this failure log" --uploaded-file failure.log
printf "summarize current status" | arcanist sessions send abc123 --prompt-stdin --json
arcanist sessions send abc123 "retry-safe send" --idempotency-key 1f0e6f1a-...

JSON mode returns {sessionId, promptId?}.

arcanist sessions stop <session-id>

Stops the active run for a session. Idempotent: if no sandbox is active, the server returns already_stopped.

arcanist sessions stop abc123
arcanist sessions stop abc123 --json

JSON mode returns {sessionId, status}. status is the server stop status or, on a 409 stop-block, the block reason; it is an open set. Known values include stopping, stopped, already_stopped, not_stoppable, and lifecycle phase names.

arcanist sessions get <session-id>

arcanist sessions get abc123
arcanist sessions get abc123 --json

Human-readable output includes PR: <url> (<branch>) when the session has opened a PR, or Branch: <branch> when a produced branch is known but no PR URL is present yet. If publishing is still settling, rerun sessions get; JSON mode returns the raw session payload, with result fields at .session.prUrl, .session.publishedBranch, and .session.lastBranch.

arcanist sessions list

arcanist sessions list
arcanist sessions list --status idle --limit 20 --json
arcanist sessions list --search "architect agent" --repo your-org/your-repo
arcanist sessions list --scope business --cursor <cursor>

JSON mode returns {sessions, nextCursor}. Search is metadata-only: generated titles and repo metadata.

arcanist sessions search <query>

arcanist sessions search "architect agent"
arcanist sessions search "mcp debugging" --repo your-org/your-repo --json
arcanist sessions search "repo access" --status idle --scope business --limit 20 --cursor <cursor>

Uses the same metadata-only index and filters as sessions list: --status, --scope, --repo, --limit, and --cursor.

arcanist sessions events <session-id>

Reads canonical session replay events. Cursors are sequence-based.

arcanist sessions events abc123 --json
arcanist sessions events abc123 --after-sequence 50 --limit 250 --json
arcanist sessions events abc123 --before-sequence 100 --poll-interval 500 --json
arcanist sessions events abc123 --prompt-id p-123 --json
arcanist sessions events abc123 --follow --json

--after and --before are aliases for --after-sequence and --before-sequence.

JSON mode without --follow returns one JSON object from /events/history: {events: [...], ...}. Canonical events carry phase.

Follow mode emits NDJSON, one {sequence, type, data} object per line, until the session becomes idle. Actionable follow-mode signals:

• PR opened or updated: pr_created / pr_updated; URL at data.prUrl.
• Waiting for human input: question; question text at data.question.
• Terminal: prompt_completed, prompt_failed, and session_idle. Follow JSON mode suppresses lifecycle status frames, so key on these event names rather than waiting_for_input.

arcanist sessions transcript <session-id>

Renders a session transcript from the stored session export.

arcanist sessions transcript abc123
arcanist sessions transcript abc123 --json

arcanist sessions watch <session-id>

Watches session activity until the session becomes idle. For machine-readable streaming, prefer arcanist sessions events --follow --json.

arcanist sessions watch abc123
arcanist sessions watch abc123 --poll-interval 500

arcanist sessions usage <session-id>

arcanist sessions usage abc123
arcanist sessions usage abc123 --json

arcanist automations create <repo-url> [prompt]

Creates a scheduled automation for a GitHub repo. Create/delete require a write-scoped CLI token; read-scoped tokens can list automations. The server validates repo access, normalizes cron expressions, dedupes retries by repo+cron+prompt, and caps each business at 20 enabled rules.

arcanist automations create your-org/your-repo "summarize new regressions" --cron "*/15 * * * *"
printf "summarize new regressions" | arcanist automations create your-org/your-repo --prompt-stdin --cron "*/15 * * * *" --json
arcanist automations create https://github.com/your-org/your-repo - --cron "0 14 * * 1-5" --name "Weekday summary"

JSON mode prints the created rule. Human-readable mode prints the rule ID, repo, normalized cron, and next fire time.

arcanist automations list

arcanist automations list
arcanist automations list --limit 20 --json
arcanist automations list --cursor <cursor>
arcanist automations list --all --json

Default output reads one page. --all follows pagination until completion. JSON mode returns {items, nextCursor}.

arcanist automations delete <id>

Deletes a scheduled automation. Interactive mode prompts for confirmation; pass --yes for non-interactive use. --json requires --yes.

arcanist automations delete rule_123
arcanist automations delete rule_123 --yes --json

arcanist tokens list

arcanist tokens list
arcanist tokens list --limit 10 --json
arcanist tokens list --cursor <cursor> --json

arcanist tokens create

Creates a CLI token and prints the plaintext token exactly once.

arcanist tokens create --scope read
arcanist tokens create --scope read --expires-in-days 30 --json

Read-scoped tokens cannot create write-scoped tokens; the server enforces that and returns 403.

arcanist tokens revoke <id>

arcanist tokens revoke 42
arcanist tokens revoke 42 --yes --json

Under --json, --yes is required.

Automation recipes

Run a prompt on a schedule and alert only when the prompt itself fails — sessions create --wait makes the exit code reflect the prompt outcome:

*/15 * * * * printf 'summarize new error-tracker regressions' | \
  ARCANIST_TOKEN=arc_... \
  arcanist sessions create your-org/your-repo --prompt-stdin --wait \
  || notify-send "Arcanist scheduled run failed"

Chain commands with --json and jq:

SESSION_ID=$(arcanist sessions create your-org/your-repo "audit dependency licenses" --json | jq -r .sessionId)
arcanist sessions events "$SESSION_ID" --follow --json | jq -r 'select(.type == "assistant_message")'

Verify a freshly deployed change with a guaranteed-fresh sandbox:

arcanist sessions create your-org/your-repo "verify the new rate limiter is active" --cold --wait

For cron, prefer ARCANIST_TOKEN or a logged-in ~/.arcanist/config.json over passing --token on the command line.

To capture the PR URL after a successful run, read the best-effort result fields from create --wait --json:

RESULT=$(arcanist sessions create your-org/your-repo "fix the flaky test" --wait --json)
PR_URL=$(jq -r '.prUrl // empty' <<<"$RESULT")
SESSION_ID=$(jq -r '.sessionId' <<<"$RESULT")
[ -n "$PR_URL" ] || { echo "PR URL not ready for $SESSION_ID" >&2; exit 1; }

Troubleshooting

• 401 on login verification: token may be invalid or expired. Regenerate in Settings > CLI Tokens.
• 401 on a previously working token: the token may have expired or been revoked in Settings. Regenerate and log in again.
• You do not have access to this repository on GitHub: the token's user lacks repo access; fix the GitHub connection or use an accessible repo.
• command not found: run npm install -g @tryarcanist/cli.