CLI Reference

Run AI-powered workflows from your terminal.

Prerequisites

1. Clone the repository and install dependencies:

   git clone https://github.com/coleam00/Archon
   cd Archon
   bun install

2. Make CLI globally available (recommended):

   cd packages/cli
   bun link

   This creates an archon command available from anywhere.

3. Authenticate with Claude:

   claude /login

Note: Examples below use archon (after bun link). If you skip step 2, use bun run cli from the repo directory instead.

Quick Start

# List available workflows (requires a git repo, a registered folder project, or --folder on first use)
archon workflow list --cwd /path/to/repo

# Run a workflow (auto-creates isolated worktree by default)
archon workflow run assist --cwd /path/to/repo "Explain the authentication flow"

# Explicit branch name for the worktree
archon workflow run plan --cwd /path/to/repo --branch feature-auth "Add OAuth support"

# Opt out of isolation (run in live checkout)
archon workflow run assist --cwd /path/to/repo --no-worktree "Quick question"

Note: Workflow and isolation commands normally require running from within a git repository (running from subdirectories automatically resolves to the repo root). A non-git directory also works if it’s a registered folder project — or on first use by passing --folder, which registers it and runs in place. The version, help, chat, setup, serve, and doctor commands work anywhere.

Commands

chat <message>

Send a message to the orchestrator for a one-off AI interaction.

archon chat "What does the orchestrator do?"

setup

Interactive setup wizard for credentials and configuration.

archon setup                      # writes ~/.archon/.env (home scope, default)
archon setup --scope project      # writes <cwd>/.archon/.env instead
archon setup --force              # overwrite instead of merging (backup still written)
archon setup --spawn              # open in a new terminal window

Flags:

Flag	Effect
--scope home	Write to ~/.archon/.env (default). Applies to every project.
--scope project	Write to <cwd>/.archon/.env. Overrides user scope for this repo only.
--force	Overwrite the target file wholesale instead of merging. A timestamped backup is still written.
--spawn	Open setup wizard in a new terminal window.

Write safety: archon setup never writes to <cwd>/.env — that file belongs to you. The wizard always targets one archon-owned file chosen by --scope, merges into existing content (so user-added keys survive), and writes a timestamped backup before every rewrite (e.g. ~/.archon/.env.archon-backup-2026-04-20T09-28-11-000Z).

Default assistant + chat model: after you pick the default assistant, the wizard offers an optional default chat model for it — a short curated list (e.g. sonnet/opus/haiku for Claude) plus an “Other…” free-text entry. Press Enter to keep the SDK default. Your selection is recorded in ~/.archon/config.yaml as defaultAssistant (plus assistants.<provider>.model when you chose a model) — the same write as archon ai default <provider> [<model>] — and re-running setup shows the current model. Pi skips the model prompt because its backend/model pair is chosen earlier in the wizard.

doctor

Verify your Archon setup. Runs a checklist of common failure points: Claude binary spawn, Codex binary resolution (env → config → vendor → autodetect, reporting which source resolved), gh CLI auth, Pi auth (when Pi is configured as default), OpenCode runtime SDK presence, database reachability, workspace writability, bundled defaults, folder-project detection (contained repos, when run from one), telemetry state, AI credentials (connected provider count, best-effort), and adapter token pings (Slack/Telegram, best-effort).

archon doctor
archon doctor --full   # also probe the OpenCode runtime SDK even when it isn't the configured assistant

The Codex check skips (never fails) when Codex isn’t the configured assistant anywhere and no OpenAI credential is connected, so Claude-only users aren’t nagged about a binary they’ll never use. The OpenCode check only probes that the embedded runtime SDK module resolves — it never boots the runtime (which spawns a child process and binds a port) — and skips unless OpenCode is the configured assistant or --full is passed.

Exit code 0 if all checks pass or are skipped; 1 if any critical check fails. Adapter pings degrade to skip on network errors — a flaky connection does not flip the result red.

Also runs automatically at the end of archon setup (optional).

auth github

Connect the current CLI user’s GitHub identity via the GitHub device flow, so workflow commits, PR comments, and pushes attribute to you instead of the bot.

archon auth github

Only meaningful on multi-user installs running GitHub App mode (GITHUB_APP_ID + GITHUB_APP_CLIENT_ID) with TOKEN_ENCRYPTION_KEY set — solo GITHUB_TOKEN installs don’t need it and the command exits with an explanatory error. Your CLI identity is resolved from ARCHON_USER_ID (explicit override) or $USER / $USERNAME, mapped to a stable Archon user via the cli platform identity.

The command prints a verification_uri and a one-time user_code; visit the URL, enter the code, and authorize. On success the access/refresh tokens are stored encrypted (AES-256-GCM) in Archon’s database. Exit code 0 on success; 1 if per-user GitHub is disabled, the identity can’t be resolved, the code expires, or authorization is denied.

ai

Manage per-user AI-provider credentials (API keys + subscriptions) and model-tier config. CLI identity is resolved from ARCHON_USER_ID (explicit override) or $USER / $USERNAME, mapped to a stable Archon user via the cli platform identity — the same as auth github.

The credential subcommands (key set, login, list, logout) work on any install — the vault is auto-provisioned. CLI identity is resolved from ARCHON_USER_ID or $USER/$USERNAME. The config subcommands (tier, alias, default) are ungated — they write ~/.archon/config.yaml and need no identity.

# --- Provider credentials (any install — vault auto-provisioned) ---
archon ai key set <vendor>       # connect an API key (masked prompt or piped stdin — never argv)
archon ai login <vendor>         # connect a subscription via OAuth (anthropic, openai, or github-copilot)
archon ai list                   # list connected credentials (metadata only, no secrets)
archon ai logout <vendor>        # disconnect a credential

# --- Model tiers + aliases + default assistant (ungated config) ---
archon ai tier set <small|medium|large> <provider> <model> [--effort <effort>] [--scope user|install]
archon ai tier list [--json]     # show configured tiers (install + yours) vs built-in defaults
archon ai tier unset <small|medium|large> [--scope user|install]
archon ai alias set <@name> <provider> <model> [--effort <effort>] [--scope user|install]
archon ai alias list [--json]    # show @custom aliases (install + yours)
archon ai alias unset <@name> [--scope user|install]
archon ai default <provider> [<model>] [--scope user|install]   # set the default assistant (+ optional chat model)

Credential ids are vendor-keyed (anthropic, openai, github-copilot, plus the Pi backends like openrouter); legacy claude/codex/copilot are accepted and normalized with a printed notice. ai login supports subscription login for anthropic, openai (ChatGPT/Codex), and github-copilot. The openai login is an Archon-owned PKCE flow (#1924): authorize in the browser, then paste the authorization code or the full localhost:1455 redirect URL back at the prompt — nothing needs to listen on that port. The API key is never read from argv (it would leak into shell history): pipe it (echo "$KEY" | archon ai key set openrouter) or type it at the masked prompt.

ai tier, ai alias, and ai default edit the same tiers: / aliases: / defaultAssistant config you can hand-write in ~/.archon/config.yaml (see Configuration) or edit from the console AI Settings page. An unknown provider exits non-zero; tier unset removes the override so the tier falls back to its built-in preset. The full per-user setup walkthrough is in Per-user credentials and AI Settings.

ai default <provider> [<model>] (default chat model). The optional <model> sets the default chat model alongside the assistant. At --scope install it writes assistants.<provider>.model in ~/.archon/config.yaml (omitting the model leaves that field untouched). At --scope user the provider and model are written atomically to your prefs row — archon ai default pi --scope user clears any previous model pin, since a pin is only meaningful for the provider it was set with. Your chat model applies to direct chat only; workflow nodes keep resolving the large tier. The model may also be an @alias or tier keyword.

--scope user (per-user overrides). On any of the config subcommands, --scope user writes your personal prefs row in Archon’s database instead of the shared config.yaml. Your tiers/aliases/default override the install config for runs and chats you start — nobody else’s. It needs a resolvable CLI identity (ARCHON_USER_ID or $USER) but no TOKEN_ENCRYPTION_KEY (model names aren’t secrets). ai tier list / ai alias list show both scopes, marking your overrides with [just you]. The same scopes are editable in the console as the “This install / Just me” toggle on AI Settings.

telemetry status

Show the current anonymous telemetry state: whether it is enabled, the opt-out reason if not, the install UUID, the active PostHog host, and the key source.

archon telemetry status

Useful for verifying that an opt-out env var (DO_NOT_TRACK=1, ARCHON_TELEMETRY_DISABLED=1, CI=true, POSTHOG_API_KEY=off) is being picked up. Inspecting status never creates a telemetry-id file while opted out.

telemetry reset

Rotate the persisted anonymous install UUID at ~/.archon/telemetry-id. The previous ID is overwritten and not recoverable.

archon telemetry reset

Exit code 0 on success; 1 if the ID file cannot be written.

workflow list

List workflows available in target directory.

archon workflow list --cwd /path/to/repo

# Machine-readable output for scripting
archon workflow list --cwd /path/to/repo --json

Discovers flat, one-level grouped, and exact <pack>/<workflow>/ packaged layouts from .archon/workflows/ and ~/.archon/workflows/, plus bundled defaults. See Global Workflows.

Flags:

Flag	Effect
--cwd <path>	Target directory (required for most use cases)
--json	Output machine-readable JSON instead of formatted text

With --json, outputs { "workflows": [...], "errors": [...] }. Optional fields (provider, model, modelReasoningEffort, webSearchMode, parseWarnings) are omitted when not set on a workflow. Each parseWarnings entry is a full warning message naming a key the engine dropped, the node it was found on, and what to write instead — see Unknown keys.

workflow run <name> [message]

Run a workflow with an optional user message.

# Basic usage
archon workflow run assist --cwd /path/to/repo "What does this function do?"

# With isolation
archon workflow run plan --cwd /path/to/repo --branch feature-x "Add caching"

Progress events (node start/complete/fail/skip, approval gates) are written to stderr during execution.

If the workflow’s YAML declares keys the engine ignores, a warning naming each one is written to stderr before the run starts. This matters to --detach --json callers: --json silences all logging, so stderr is the only channel left, and it keeps stdout to exactly the JSON payload.

Note that a real run emits a JSON payload only under --detach. Without it, --json suppresses logs but the command still prints human progress to stdout (Running workflow: …), so do not pipe a plain real run --json into a parser. The side-effect-free --dry-run --json mode below is the other exception: it emits exactly one complete trace document. See Unknown keys.

Flags:

Flag	Effect
--cwd <path>	Target directory (required for most use cases)
--branch <name>	Explicit branch name for the worktree
--from <branch>, --from-branch <branch>	Start-point for the new worktree only — unlike --base, it does not change the PR target
--base <branch>	Per-dispatch base override for a single run. Sets both the worktree cut-from and the PR target ($BASE_BRANCH), and outranks worktree.baseBranch in config plus the codebase default — see Base branch precedence below. The branch must already exist on the remote; a missing one is a hard error, not a fallback. Combine with --from to drive the two separately. Rejected with --no-worktree, --folder, and workflows pinning worktree.enabled: false.
--no-worktree	Opt out of isolation — run directly in live checkout
--folder	Register the current non-git directory as a folder project (first use) and run in place — no worktree. Rejects --branch/--from/--base.
--container	Run a folder project inside an overlay-isolated Docker container instead of in place (writes land in an overlay, not the live root, until an approval-gated write-back). Folder-only; a repo project errors. Requires the runner image (bun run build:runner-image). Pauses docker stop the container; --resume/approve/reject rediscover and restart it. See the Container isolation guide and configuration.
--resume	Resume from last failed run at the working path (skips completed nodes)
--quiet, -q	Suppress all progress output to stderr
--verbose, -v	Also show tool-level events (tool name and duration)
--detach	Run in a detached background child and return immediately. The child does all the work; find it later with workflow runs/workflow get. Child stdout/stderr is captured to ~/.archon/logs/detached-run-<id>.log. Combine with --json for a machine-readable ack.
--dry-run	Simulate deterministic DAG control flow in memory. Creates no run, worktree, session, event, artifact, or provider request.
--stubs <path>	YAML mapping of node ids to scalar or structured outputs for --dry-run. Relative paths resolve from --cwd.
--exec-code	During --dry-run, execute trusted bash:/script: nodes locally instead of requiring stubs. Default is no code execution.
--pause-at-gates	During --dry-run, stop at the first approval gate instead of auto-approving it.

Deterministic dry-run

Use dry-run to test DAG routing, joins, loops, when:, strict output fields, and variable substitution without starting a real workflow:

cat > stubs.yaml <<'YAML'
classify:
  issue_type: bug
  severity: high
investigate: "Root cause: stale cache"
YAML

archon workflow run triage --cwd /path/to/repo \
  --dry-run --stubs stubs.yaml "Issue #2100"

# One complete JSON document, safe to pipe in CI
archon workflow run triage --cwd /path/to/repo \
  --dry-run --stubs stubs.yaml --json | jq '.trace, .outcome'

The stub file must contain one YAML mapping. Each value is either a string or an object. Object stubs are preserved as structured output, so downstream $classify.output.severity references behave like live structured producers. A reachable AI, bash, or script node without a stub fails the simulation and appears in missingStubs; stubs for unknown or unreachable nodes appear in unusedStubs. Whole-output references retain their normal lenient behavior, while invalid strict $node.output.field references fail the consuming node exactly as they do in a real run. See Node Output References.

By default, bash and script nodes are never executed. --exec-code is an explicit opt-in for trusted local workflow code and is the only dry-run mode that can cause code-level side effects. Approval nodes auto-complete unless --pause-at-gates is set. Runtime workflow: sub-runs are reported as unsupported instead of being launched. Dry-run is incompatible with lifecycle and isolation flags such as --branch, --no-worktree, --folder, --container, --resume, and --detach.

The ordered trace records each node as completed, stubbed, skipped, failed, or paused, including its reason, resolved text, safe output, and final outcome. This validates deterministic engine wiring; it does not validate model reasoning. It adds no workflow-YAML language surface and follows the workflow language constitution: YAML coordinates, code computes, and agents judge.

Default (no flags):

• Creates worktree with auto-generated branch (archon/task-<workflow>-<timestamp>)
• Auto-registers codebase if in a git repo

With --branch:

• Creates/reuses worktree at ~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>/
• Reuses existing worktree if healthy

With --no-worktree:

• Runs in target directory directly (no isolation)
• Mutually exclusive with --branch, --from, and --base

Base branch precedence

“Base branch” means two things, and by default one flag sets both: the cut-from (what git worktree add branches off) and the PR target ($BASE_BRANCH, which bash nodes pass to gh pr create --base). Four sources can supply it, highest first:

Precedence	Source	Scope
1	--base <branch>	one dispatch
2	worktree.baseBranch in .archon/config.yaml	the repo
3	The registered codebase’s stored default branch	the repo
4	Git auto-detection (origin/HEAD, then origin/main)	the repo

Levels 2—4 are static per repo, so a run that needs a different base than its neighbours had to edit config — global, and racy when several runs dispatch at once. --base is the per-dispatch level, which is what makes parallel multi-base dispatch (epic slices, A/B variants) config-free.

Scope: the dispatched run only. A workflow: node with isolation: worktree creates a worktree for its child run, and that worktree is cut using levels 2—4 only — --base and --from do not propagate to sub-run children. A parent dispatched with --base release/2.0 still branches its isolated children off the repo’s configured base. See Choosing the child’s checkout.

Driving cut-from and PR target separately. --from overrides only the cut-from, so pairing the two flags splits them:

# Branch off release/2.0, but open the PR against dev
archon workflow run implement --from origin/release/2.0 --base dev "Backport the fix"

--from is handed to git worktree add verbatim, so a remote ref such as origin/release/2.0 works. Note the sync-before-create step refreshes the --base branch, not the --from start point — pass a remote ref when the local copy of the start point may be stale.

Where --base is rejected (rather than half-applied): with --no-worktree, against a folder project, and against a workflow pinning worktree.enabled: false. None of these create a worktree, so the flag could only move the PR target — which would report a base no worktree was ever cut from.

When an existing worktree is adopted — --branch naming a healthy worktree, or --resume continuing a prior run — the cut-from is already fixed, so --base changes only the PR target. Archon warns in both cases.

Name Matching:

Workflow names are resolved using a 4-tier fallback hierarchy. This applies consistently across the CLI and all chat platforms (Slack, Telegram, Web, GitHub, Discord):

1. Exact match - archon-assist matches archon-assist
2. Case-insensitive - Archon-Assist matches archon-assist
3. Suffix match - assist matches archon-assist (looks for -assist suffix)
4. Substring match - smart matches archon-smart-pr-review

If multiple workflows match at the same tier, an error lists the candidates:

Ambiguous workflow 'review'. Did you mean:
  - archon-review
  - custom-review

workflow status

Show active workflow runs (running and paused) across all worktrees. For full history (all statuses) scoped to the current project, use workflow runs.

archon workflow status
archon workflow status --json
archon workflow status --verbose   # add a per-node summary for each run
archon workflow status --json --verbose

workflow runs

List recent runs of every status (completed, failed, cancelled, running, paused) for the current project. The project is resolved from cwd the same way workflow run does. Complements workflow status (which is active-only).

archon workflow runs
archon workflow runs --json
archon workflow runs --status failed   # filter to one status
archon workflow runs --limit 50        # cap rows (default 20)
archon workflow runs --all             # list across all projects (ignore cwd scope)

If cwd is not a registered project, the command falls back to a global list and says so — --json carries this as a scopeFallback: true field so a consuming agent never mistakes a global result for a project-scoped one.

The listing shows short 8-character run ids. Every <run-id> command below (get, resume, abandon, approve, reject) accepts these short ids when run from the project directory: a unique prefix resolves to the full id, an ambiguous prefix errors, and full ids keep working from any directory. Short ids from --all rows belonging to other projects can’t be resolved — use the full id from --json for those.

workflow get

Show detail for a single run by ID, regardless of status (unlike status, which is active-only). Use it to answer “did that run pass?” for a completed/failed run. Exits non-zero when the run is not found.

archon workflow get <run-id>
archon workflow get <run-id> --json
archon workflow get <run-id> --verbose   # add the per-node summary
archon workflow get <run-id> --json --verbose

For both commands, --json --verbose adds a nodes array. Nodes are ordered by the first appearance of each node in the deterministically ordered event stream. Every entry includes nodeId and state; nodes with a start event include the original ISO startedAt, and terminal nodes with both start and end events include durationMs. Completed nodes may include an outputPreview, truncated after 200 characters with ASCII ..., while failed nodes include error (or Unknown error when none was recorded).

Add --events to --json --verbose to return raw events rows instead of nodes for debugging. Raw events are not the recommended integration surface.

workflow resume

Resume a failed or paused workflow run. Re-executes the workflow, automatically skipping nodes that completed in the prior run.

archon workflow resume <run-id>
archon workflow resume <run-id> --json   # validate + ack only; does NOT re-execute inline

In --json mode the command is a non-blocking control-plane ack: it validates the run is resumable and reports its state but does not re-execute inline (execution streams output to stdout, which would corrupt the JSON). To actually drive a resumable run to completion, use the blocking form or workflow run <name> --resume --detach.

workflow abandon

Discard a workflow run (marks it as cancelled). Use this to unblock a worktree when you don’t want to resume — the path lock is released immediately so a new workflow can start.

archon workflow abandon <run-id>
archon workflow abandon <run-id> --json

Sub-run trees (#2121 Phase 2): abandoning a parent that spawned workflow: sub-runs cascade-cancels every non-terminal descendant (children and grandchildren; already-terminal runs are left alone). The cancel is cooperative — each child’s executor aborts at its next status check (~10s; no hard subprocess kill). If part of the tree could not be reached, the command reports the count so you know descendants may still be alive. Conversely, abandoning a child that its parent is paused-and-blocked on strands that parent (nothing re-fires the auto-resume hook); the command surfaces the blocked parent’s run id so you can resume it (which fails the sub-run node cleanly) or abandon it too.

workflow approve

Approve a paused workflow run at an interactive approval gate. Optionally provide a comment that is available to the workflow via $LOOP_USER_INPUT.

Sub-run child gates (#2121 Phase 2): when a workflow: sub-run pauses at its own gate, the parent run pauses “blocked on child”. Approve (or reject) the child by its own run id — the id shown in the parent’s block message — not the parent’s; the parent auto-resumes when the child completes. A child gate is the exception: it works for a 1:1 sub-run, but a child that pauses inside a fan_out: expansion fails the node instead — a parent has one approval slot and cannot hand it to N children, so gate before or after the fan-out node rather than inside a child of it. approve/reject against the parent’s id while it’s blocked on a child are refused with a redirect to the child id.

Interactive-loop gates — finalize vs iterate: when the gate paused on an iteration that emitted the loop’s completion signal (workflow get <run-id> --json → .metadata.approval.completionSignaled is true), approving with no comment accepts the completion — the node finalizes from the already-computed output on resume, with no re-run. Approving with a comment runs another iteration using it as $LOOP_USER_INPUT. On a non-signaled gate, both forms run another iteration.

archon workflow approve <run-id>
archon workflow approve <run-id> "Looks good, proceed"
archon workflow approve <run-id> --comment "Looks good, proceed"
archon workflow approve <run-id> --json   # record approval + ack; does NOT auto-resume inline

In human mode approve/reject auto-resume the run inline. In --json mode they record the decision and return an ack without resuming (the run is left resumable for a backgrounded resume/run --resume).

workflow reject

Reject a paused workflow run at an approval gate. Optionally provide a reason that is available to the workflow via $REJECTION_REASON.

archon workflow reject <run-id>
archon workflow reject <run-id> --reason "Needs more tests"
archon workflow reject <run-id> --json

workflow cleanup

Delete old terminal workflow run records from the database.

archon workflow cleanup        # Default: 7 days
archon workflow cleanup 30     # Custom threshold

workflow reset-sessions

Clear persisted per-node AI sessions for a workflow — the cross-run memory stored by nodes that opt in via persist_session (or workflow-level persist_sessions: true). Use it when a workflow should forget its prior conversation and start fresh.

archon workflow reset-sessions <workflow-name> --yes             # ALL scopes (cross-scope wipe)
archon workflow reset-sessions <workflow-name> --scope <key>     # one scope only
archon workflow reset-sessions <workflow-name> --node <id> --yes # single node, still all scopes → needs --yes
archon workflow reset-sessions <workflow-name> --scope <key> --json

Flags:

Flag	Required	Description
--scope	No	Scope key to reset — typically the conversation UUID. Omitting it wipes every scope and requires --yes.
--node	No	Restrict the reset to a single node id.
--yes	Only for cross-scope wipes	Confirm a wipe across all scopes (when --scope is omitted).
--json	No	Machine-readable output ({ success, deleted }).

Extra positional arguments are rejected rather than silently reinterpreted — use --node <id> to filter by node, since this is a destructive command.

workflow event emit

Emit a workflow event directly to the database. Primarily used inside workflow loop prompts to record story-level lifecycle events.

archon workflow event emit --run-id <uuid> --type <event-type> [--data <json>]

Flags:

Flag	Required	Description
--run-id	Yes	UUID of the workflow run
--type	Yes	Event type (e.g., ralph_story_started, node_completed)
--data	No	JSON string attached to the event. Invalid JSON prints a warning and is ignored.

Exit code: 0 on success, 1 when --run-id, --type is missing, or --type is not a valid event type. Event persistence is best-effort (non-throwing) — check server logs if events appear missing.

isolation list

Show all active worktree environments.

archon isolation list

Groups by codebase, shows branch, workflow type, platform, and days since activity.

Includes worktrees created for workflow: sub-run children that declared isolation: worktree (branch archon/task-<parentRunId8>-<nodeId>-<hash>-child-<n>) — they are tracked and cleaned up exactly like top-level run worktrees. Avoid cleanup/complete on one while its run tree is still resumable: a resume reuses the child’s recorded worktree and fails if it has been removed.

isolation cleanup [days]

Remove stale environments.

# Default: 7 days
archon isolation cleanup

# Custom threshold
archon isolation cleanup 14

# Remove environments with branches merged into main (also deletes remote branches)
archon isolation cleanup --merged

# Also remove environments whose PRs were closed without merging
archon isolation cleanup --merged --include-closed

Merge detection uses three signals in order: git branch ancestry (fast-forward / merge commit), patch equivalence (squash-merge via git cherry), and GitHub PR state via the gh CLI. The gh CLI is optional — if absent, only git signals are used.

By default, branches with a CLOSED PR are skipped. Pass --include-closed to clean those up as well. Branches with an OPEN PR are always skipped.

validate workflows [name]

Validate workflow YAML definitions and their referenced resources (command files, MCP configs, skill directories).

archon validate workflows                 # Validate all workflows
archon validate workflows my-workflow     # Validate a single workflow
archon validate workflows my-workflow --json  # Machine-readable JSON output

Checks: YAML syntax, DAG structure (cycles, dependency refs), command file existence, MCP config files, skill directories, provider compatibility, and tier/alias model refs. For bundled and global workflows, validation rejects @custom model aliases because they are not portable across projects; use small, medium, large, or a literal provider model string instead. Returns actionable error messages with “did you mean?” suggestions for typos.

Exit code: 0 = all valid, 1 = errors found.

validate commands [name]

Validate command files (.md) in .archon/commands/.

archon validate commands                  # Validate all commands
archon validate commands my-command       # Validate a single command

Checks: file exists, non-empty, valid name.

Exit code: 0 = all valid, 1 = errors found.

complete <branch> [branch2 ...]

Remove a branch’s worktree, local branch, and remote branch, and mark its isolation environment as destroyed.

archon complete feature-auth
archon complete feature-auth --force  # bypass uncommitted-changes check

Flags:

Flag	Effect
--force	Skip uncommitted-changes guard

Use this after a PR is merged and you no longer need the worktree or branches. Accepts multiple branch names in one call.

serve

Start the web UI server. On first run, downloads a pre-built web UI tarball from the matching GitHub release, verifies the SHA-256 checksum, and extracts it. Subsequent runs use the cached copy.

Binary installs only — in development, use bun run dev instead.

# Start web UI server (downloads on first run)
archon serve

# Override the default port
archon serve --port 4000

# Download the web UI without starting the server
archon serve --download-only

Flags:

Flag	Effect
--port <port>	Override server port (default: 3090, range: 1–65535)
--download-only	Download and cache the web UI, then exit without starting the server

The cached web UI is stored at ~/.archon/web-dist/<version>/. Each version is cached independently, so upgrading the binary automatically downloads the matching web UI.

skill install [path]

Install the bundled Archon skills into both .claude/skills/ (Claude Code) and .agents/skills/ (Codex) directories of a project. Always overwrites existing files to ensure the latest version shipped with the current Archon binary is installed.

# Install into the current directory
archon skill install

# Install into a specific project
archon skill install /path/to/project

Two skills are installed: archon, which teaches the assistant how to work with Archon workflows, commands, and project conventions; and manage-run, a focused skill for inspecting and controlling workflow runs via the archon CLI. Each skill is written to both .claude/skills/<skill>/ (Claude Code) and .agents/skills/<skill>/ (Codex’s canonical project-level skill path). Both are also installed automatically during archon setup.

version

Show version, build type, and database info.

archon version

Global Options

Option	Effect
--cwd <path>	Override working directory (default: current directory)
--quiet, -q	Reduce log verbosity to warnings and errors only
--verbose, -v	Show debug-level output
--json	Output machine-readable JSON (workflow list, status, runs, get, and the write commands approve/reject/abandon/resume). Implies log suppression so stdout is exactly the JSON payload.
--events	With verbose JSON workflow status/get, return raw event rows instead of ordered node summaries.
--help, -h	Show help message

Working Directory

The CLI determines where to run based on:

1. --cwd flag (if provided)
2. Current directory (default)

Running from a subdirectory (e.g., /repo/packages/cli) automatically resolves to the git repository root (e.g., /repo).

When using --branch, workflows run inside the worktree directory.

Commands and workflows are loaded from the working directory at runtime. The CLI reads directly from disk, so it picks up uncommitted changes immediately. This is different from the server (Telegram/Slack/GitHub), which reads from the workspace clone at ~/.archon/workspaces/ — that clone only syncs from the remote before worktree creation, so changes must be pushed to take effect there.

Environment

At startup, the CLI strips all Bun-auto-loaded CWD .env keys and nested Claude Code session markers from process.env, then loads two archon-owned env files with override: true. Keys in archon-owned files pass through to AI subprocesses — no allowlist filtering.

On startup, the CLI:

1. Strips <cwd>/.env* keys + CLAUDECODE markers from process.env (via stripCwdEnv). Emits [archon] stripped N keys from <cwd> (...) when N > 0.
2. Loads ~/.archon/.env (user scope). Emits [archon] loaded N keys … when N > 0 and ARCHON_VERBOSE_BOOT=1 or LOG_LEVEL=debug/trace is set.
3. Loads <cwd>/.archon/.env (project scope, overrides user scope). Same verbosity gate as step 2.
4. Auto-enables global Claude auth if no explicit tokens are set.

<cwd>/.env is never loaded — it belongs to the target project. See Configuration Reference: .env File Locations for the full three-path model.

Database

• Without DATABASE_URL (default): Uses SQLite at ~/.archon/archon.db — zero setup, auto-initialized on first run
• With DATABASE_URL: Uses PostgreSQL (optional, for cloud/advanced deployments)

Both work transparently. Most users never need to configure a database.

Examples

# One-off AI chat
archon chat "How does error handling work in this codebase?"

# Interactive setup wizard
archon setup

# Quick question (auto-isolated in archon/task-assist-<timestamp>)
archon workflow run assist --cwd ~/projects/my-app "How does error handling work here?"

# Quick question without isolation
archon workflow run assist --cwd ~/projects/my-app --no-worktree "How does error handling work here?"

# Plan a feature (auto-isolated)
archon workflow run plan --cwd ~/projects/my-app "Add rate limiting to the API"

# Implement with explicit branch name
archon workflow run implement --cwd ~/projects/my-app --branch feature-rate-limit "Add rate limiting"

# Branch from a specific source branch instead of auto-detected default
archon workflow run implement --cwd ~/projects/my-app --branch test-adapters --from feature/extract-adapters "Test adapter changes"

# Approve or reject a paused workflow
archon workflow approve <run-id> "Ship it"
archon workflow reject <run-id> --reason "Missing test coverage"

# Check worktrees after work session
archon isolation list

# Clean up old worktrees
archon isolation cleanup