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) |