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 ]
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.
archboard check > check.json 2> check.log
Exit codes#
Every command uses the same codes. A command's own page lists the refusals that it can give,
each with its code.
Exit Meaning
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.
Option What 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#
Variable What 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#
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
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
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
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