GitHub

CLI overview

Every command that an agent or a person runs, generated from the CLI's own contracts. Start with how a command finds its vault and what it prints.

On this page

This reference comes from the CLI of release 0.5.0. Each command finds its vault the way Git finds its repository: from the working directory, or from the directory that -C names. Commands that need the server start it on loopback when nothing answers.

archboard [-C <dir>] [--url <url>] [--text] <command> [options]
archboard help <command>

What a command prints#

A command prints its result as JSON on standard output, and its diagnostics as lines on standard error. A script reads the JSON. A person reads the lines. With --text anywhere before --, a command prints its result as coloured text instead of JSON.

Keep both streams
archboard check > check.json 2> check.log
echo "exit $?"

Exit codes#

Every command uses the same codes. A command's own page lists the refusals that it can give, each with its code.

ExitMeaning
0 The command did what it said. A check found nothing that you must fix. Information can still print.
1 An error. archboard check exits 1 while a check still has a diagnostic or a warning.
2 A usage error or a refused operation: a claim held, revoked or missing, a revision that moved, or no vault found. Read the model again and retry.
3 The Archboard server did not answer and could not start.
4 Something local that the command needs is missing: an open browser pane, or Chromium or ffmpeg to record a walkthrough.

Shared options#

These options ride on every request of one invocation. A command's help lists the ones that it reads, and it refuses any other.

OptionWhat it does
--url <url> The Archboard server to talk to; overrides ARCHBOARD_URL. Default http://127.0.0.1:4242.
-C <dir> Find the vault from this directory instead of the working directory, the way git -C finds a repository; other relative paths still resolve against the working directory.
--doing <line> One present-tense line saying what this write does, shown on every pane holding the model and never written to it.
--as-session <thread> The agent session acting, so it is not told about what it did itself.
--text Print the result as coloured text for a person instead of JSON.

Environment#

VariableWhat it does
ARCHBOARD_URL The server that commands talk to. --url overrides it.
ARCHBOARD_NO_AUTOSTART Set it to 1, and a command no longer starts the server when nothing answers. It exits 3 instead.
ARCHBOARD_REPOS The registry of checkouts, repos.json. The global language-servers.json is beside it.
ARCHBOARD_RENDERER_CHROMIUM Names the Chromium or Chrome that draws PNG pictures and records walkthroughs, when the one on PATH is not the one to use.
ARCHBOARD_FFMPEG Names the ffmpeg that encodes a recorded walkthrough, in place of the one on PATH.
XDG_STATE_HOME On Linux, moves the state directory: the Codex sign-in, the registry and the logs.
ARCHBOARD_VAULT Refused. A command finds its vault from the working directory or -C. Unset it.
EXPRESS_SERVER_URL Refused. It is now ARCHBOARD_URL. Rename it.

Every command#

Setup, checkouts and telemetry

init Set this repository up for Archboard and hand its language servers to an agent
repo The repository checkouts on this machine and the one that is read for each repository, so a binding can name a repo instead of a directory
repo list List known repository checkouts and untracked vaults
repo add Register a repository checkout or an untracked vault
repo use Choose the checkout that this machine reads for its repository
repo forget Forget a known checkout or untracked vault
repo language-server Show, set or remove the language servers of a repository or of this machine
telemetry Show or change whether Archboard sends anonymous usage counts and error reports

The model commands

model Read an authored canonical module model
model rasterize Capture a canonical reading as a reproducible PNG
model replay Render a recorded talk to a video file, frame by frame
model config Discover the configured vocabulary or its editor schema
model schema List the JSON Schemas of the model files and requests, or print one
model init Initialize an empty canonical planning model
model archive-init Explicitly initialize private history for an untracked vault
model export Export complete canonical inputs and retained history
model import Import verified canonical inputs and complete history
model edit Edit canonical modules and independent flow behavior durably
model claim Claim canonical subjects and proposal states
model release Release a canonical subject claim
model claims Read canonical subject claims
model recover Recover the checkout's durable canonical edit
model record Record one exact retained canonical walkthrough
model render Render a canonical architecture or behavioral reading
model snapshot Write a state and its comparison state to one portable file
model locality Rank modules by how often their code changes, and find modules that change together
model footprint Compare a source branch with the architecture: which modules its commits changed
model explain Explain a captured architecture reading through the local agent
model read Read an authored canonical module model
model inspect Read one module's interface or one group's boundary
model proposals List compact proposals and current state metadata
model compare Compare coherent canonical architectural states
model retain Retain exact current architecture or original migration inputs locally
model checkpoints List retained local architecture checkpoints
model inventory Inventory original legacy boards and identity evidence
model publication Read explicit archive publication status
model publication-configure Configure an explicit archive publication destination
model publish Publish complete retained architecture history
model fetch Fetch complete archive history for a missing reading
model migrate Install an owner-authorized complete migration preview
model plan Save explicit legacy identity mappings and conflict choices

The check commands

check Run every check of the vault: semantics, code, then embeds
check all Run every check of the vault: semantics, code, then embeds
check semantics Check the canonical model, active proposals, and vocabulary
check code Inspect the source that canonical bindings and evidence anchors name
check embeds Check the reproducible architecture artifacts that this checkout embeds

The server commands

start Start the Archboard server (detached)
stop Stop the Archboard server
restart Stop the Archboard server, build the frontend and start it again
status Archboard server health and browser clients

The browser commands

browser Inspect or control the connected browser session
browser panes What every pane is showing and reading
browser open Open a second browser pane
browser close Close one browser pane
browser show Show a canonical reading in one pane
Docs

Type to search every page, command and schema.