Command reference

Every archi command, as its parser defines it. Run archi <command> --help for the same text in a terminal.

Commands that read an instance take --instance DIR (default: the current directory).

archi bundles

Inspect and check packs and bundles.

archi bundles list

Every pack and bundle installed packages register.

Option Meaning Default
--json machine-readable output
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi bundles show

One pack or bundle in full (JSON).

Argument Meaning
name
Option Meaning Default
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi bundles validate

Check manifests against the published schemas and the composition rules.

Argument Meaning
paths pack or bundle directories (or their manifest files); default: every one found
Option Meaning Default
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi render

Compose bundles and packs into one okg profile.

Option Meaning Default
--bundle BUNDLE bundle to install (repeatable; chat scalars come from the last)
--with WITH_PACKS add packs (comma-separated or repeated)
--without WITHOUT_PACKS remove packs (comma-separated or repeated)
--instance INSTANCE instance directory; the profile goes to <instance>/profiles/<name>/ .
--name NAME profile name (default: the bundle names joined by -)
--deployment DEPLOYMENT installed okg deployment directory to record in archi.lock
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi add

Add a pack to an installed instance and publish again.

Argument Meaning
pack
Option Meaning Default
--instance INSTANCE instance directory .
--deployment DEPLOYMENT okg deployment directory (default: the one archi.lock records)
--answer ID=VALUE answer one of the new pack's questions, by rendered id (repeatable)
--without PACK leave out a companion pack the new pack would bring (repeatable)
--no-okg edit and commit the deployment, but run no okg command
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi diff

Report drift from archi.lock.

Option Meaning Default
--instance INSTANCE instance directory .
--deployment DEPLOYMENT okg deployment directory (default: the one archi.lock records)
--json
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi init

Create an instance: git repo, secrets, profile, published graph.

Argument Meaning
name instance and deployment name (lowercase slug)
Option Meaning Default
--bundle BUNDLE bundle to install (repeatable; default: cern-team)
--with WITH_PACKS add packs (comma-separated or repeated)
--without WITHOUT_PACKS remove packs (comma-separated or repeated)
--dir DIR instance directory (default: ./<name>)
--data-root DATA_ROOT connector caches and checkouts, outside the instance (default: ~/.local/share/archi/<name>)
--answer ID=VALUE answer a profile question (repeatable); relative paths are made absolute
--runtime RUNTIME container runtime (default: the first that works)
--admin-email ADMIN_EMAIL Open WebUI admin account (default: admin@<name>.archi.invalid)
--no-okg write and commit the instance, but start nothing and run no okg command
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi connect

Write another agent's MCP config for this instance.

Argument Meaning
client
Option Meaning Default
--instance INSTANCE instance directory .
--print print the config (the default)
--write PATH merge into this client config (default per client: claude-code ./.mcp.json, codex ~/.codex/config.toml, openclaw ~/.openclaw/openclaw.json, mcp ./archi-mcp.json)
--show-token include the bearer token in what is printed
--embed-token with --write: write the literal token (mode 0600) instead of a ${OKG_CHAT_MCP_TOKEN} reference; refused unless the file is git-ignored

archi up

Start the instance's compose project and wire the chat to the graph.

Option Meaning Default
--instance INSTANCE instance directory .
--ollama-url OLLAMA_URL model server as the webui container reaches it (default: http://host.docker.internal:11434 when an ollama answers on this host)
--no-sync start the containers only; skip the admin sign-in and okg chat sync

archi down

Stop the instance's compose project (volumes are kept).

Option Meaning Default
--instance INSTANCE instance directory .
--purge also delete the volumes (needs --yes)
--yes

archi doctor

Okg lint + doctor + archi's footgun checks, with remediations.

Option Meaning Default
--instance INSTANCE instance directory .
--json one JSON object, for agents

archi ingest

Run okg ingest for the instance, with the credentials in its .env.

Option Meaning Default
--instance INSTANCE instance directory .
--include INCLUDE comma-separated source ids to ingest (default: every source)
--publish then publish a new generation (okg run --once --apply)

archi eval

Ask a bundle's smoke questions through the instance MCP with a local model, or score retrieval alone with --context.

Option Meaning Default
--bundle BUNDLE bundle whose smoke set to run (repeatable; default: the instance's bundles)
--instance INSTANCE instance directory (default: .) .
--model MODEL model name at the endpoint (default: the bundle's chat.default_model)
--model-url MODEL_URL OpenAI-compatible base URL (default: http://127.0.0.1:11434/v1, a local Ollama) http://127.0.0.1:11434/v1
--out OUT report directory, written straight into and replaced on the next run (default: a new <data root>/eval/<bundle>/<UTC stamp>/ per run, outside the instance repository, with latest.json naming the newest)
--keep N without --out: keep the newest N dated runs per bundle and delete older ones (default 20; 0 keeps all)
--mcp-url MCP_URL MCP endpoint (default: the instance's, http://127.0.0.1:<port>/mcp)
--chat-prompt CHAT_PROMPT the chat system prompt to give the agent (default: the instance deployment's skills/chat-system-prompt.md, the one archi up gives the chat)
--max-steps MAX_STEPS tool-call rounds allowed per question 8
--no-think ask a reasoning model to skip its thinking pass (reasoning_effort: none)
--allow-remote-model allow a model endpoint off this host or network (may cost money; off by default)
--context score retrieval instead: call the MCP search tool directly (no model) and report recall@k of each question's gold ids, with a lexical baseline arm; each run is kept under <data root>/eval/context/<bundle>/<UTC stamp>/
--questions QUESTIONS with --context: the question file, kept outside this repository (default: $ARCHI_CONTEXT_EVAL_QUESTIONS, else the bundle's eval/context.yaml)
--k K with --context: the recall cut-off (default: the file's k, else 10)
--agents ARMS also run the agent arms (default both: agent-bash,agent-graph)
--tries TRIES tries per question and arm (default 1) 1
--corpus CORPUS the raw corpus (default: the newest under <data root>/eval/raw-corpus/<bundle>/)
--reasoning-effort REASONING_EFFORT reasoning_effort sent with each agent call (for example medium)
--model-api MODEL_API the API the agent calls use: responses (/responses, OpenAI's Responses API) or chat (/chat/completions); auto, the default, is responses for api.openai.com and chat for anything else, such as a local Ollama auto
--model-key-env MODEL_KEY_ENV environment variable holding the PATH of a file with the model API key (default ARCHI_EVAL_MODEL_KEY_FILE); the key is never logged and never enters the sandbox ARCHI_EVAL_MODEL_KEY_FILE
--model-price IN/OUT[/CACHED] the model's price in dollars per million input/output[/cached input] tokens (required)
--max-output-tokens MAX_OUTPUT_TOKENS max_completion_tokens per agent call (max_output_tokens on the Responses API), also the spend guard's output bound (default 16000) 16000
--max-turns MAX_TURNS model turns per try (default 30) 30
--max-tool-calls MAX_TOOL_CALLS tool calls per try (default 200) 200
--try-seconds TRY_SECONDS wall time per try (default 900) 900.0
--cap DOLLARS spend cap in dollars for the run, judge included (required: there is no default); the run stops before a call that could cross it
--judge grade answers against the question file's answer keys with a judge model (off by default)
--judge-model JUDGE_MODEL the judge model
--judge-url JUDGE_URL the judge's OpenAI-compatible base URL (default https://api.openai.com/v1) https://api.openai.com/v1
--judge-reasoning-effort JUDGE_REASONING_EFFORT reasoning_effort for the judge (default high) high
--judge-max-output-tokens JUDGE_MAX_OUTPUT_TOKENS max_completion_tokens per judge call, also its spend bound (default 16000) 16000
--allow-low-price accept a price below $0.01 input or $0.04 output per million tokens (a local model); refused by default as a likely typo
--judge-key-env JUDGE_KEY_ENV environment variable holding the PATH of a file with the judge API key (default ARCHI_EVAL_JUDGE_KEY_FILE) ARCHI_EVAL_JUDGE_KEY_FILE
--judge-price IN/OUT[/CACHED] the judge's price, as --model-price
--judge-passes JUDGE_PASSES judge passes per answer (default 1) 1
--raw-corpus build the raw-document corpus from the instance's connector caches, under <data root>/eval/raw-corpus/<bundle>/<lock sha>/, and exit
--pack-root PACK_ROOT extra directory of <name>/pack.yaml entries (repeatable)
--bundle-root BUNDLE_ROOT extra directory of <name>/bundle.yaml entries (repeatable)

archi ops

Status, halt, resume, promote and answer the operations automations.

Option Meaning Default
--instance INSTANCE instance directory .
--deployment DEPLOYMENT okg deployment name (default: the instance's name)
--dsn DSN graph database (default: $OKG_DSN, else the instance's secrets)

archi ops status

Levels, schedules, pending escalations, budgets and shadow scores.

Option Meaning Default
--json machine-readable output

archi ops halt

Stop every automation on this instance.

Option Meaning Default
--json machine-readable output
--as WHO who is halting (default: the OS user)
--no-cancel pause the scanner but leave runs in flight; their mediator step refuses to act

archi ops promote

Ask for an automation to go live: opens a PACT change for an operator to approve.

Argument Meaning
automation
Option Meaning Default
--json machine-readable output
--note NOTE a note for the PACT decision
--as AS_USER who is deciding (recorded as "<os user> for X")
--min-proposals MIN_PROPOSALS 30
--min-answered MIN_ANSWERED 20
--min-coverage MIN_COVERAGE 0.5
--min-agreement MIN_AGREEMENT 0.8
--max-false-rate MAX_FALSE_RATE 0.1
--no-trial go live with no shadow results, on the decision --note names (required); the change records that there is no shadow evidence, and an operator still approves it

archi ops resume

Resume the schedules halt paused.

Option Meaning Default
--json machine-readable output

archi ops pending

Escalations waiting for a person.

Option Meaning Default
--json machine-readable output

archi ops approve

Approve an escalation.

Argument Meaning
escalation_id
Option Meaning Default
--json machine-readable output
--note NOTE a note recorded with the decision
--as AS_USER who is deciding (default: the OS user)

archi ops reject

Reject an escalation.

Argument Meaning
escalation_id
Option Meaning Default
--json machine-readable output
--note NOTE a note recorded with the decision
--as AS_USER who is deciding (default: the OS user)