GitHub

The model commands

Read, write, compare, render and keep the canonical architecture model of a vault.

On this page

Every command below comes from the CLI's own contract in release 0.5.0. Run archboard help <command> for the same words at your terminal.

Command What it does
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

model #

Read an authored canonical module model

Without a subcommand, archboard model runs archboard model read, and the options before the subcommand go to it.

Examples

Terminal window
archboard model read
archboard model read 'Shop#Gateway' -C /tmp/shop

model rasterize #

Capture a canonical reading as a reproducible PNG

  • Needs the server
  • Writes files

Synopsis

archboard model rasterize [--module <id>] [--state <id>] [--scope <id>] [--focus <id>] [--hide-kind <id>] [--expand <id>] [--flow <id>] [--grammar <grammar>] [--checkpoint <id>] [--legend <layout>] [--theme <theme>] --out <file.png> [--scale <factor>] [--region <x,y,width,height>] [--url <url>] [-C <dir>]

Uses the same canonical projection and SVG renderer, then captures it through the existing local rasterizer.

Arguments

Argument What it does
--module <id> Select a module by identity or unique name
--state <id> Select an explicit architectural state
--scope <id> Open an exact module scope
--focus <id> repeatable Focus these identities
--hide-kind <id> repeatable Hide these relationship kinds
--expand <id> repeatable Open these modules beside the scope
--flow <id> One qualified flow identity or unique current or former name
--grammar <grammar> Draw sequence or flowchart One of architecture, sequence, flowchart.
--checkpoint <id> Read this exact retained checkpoint
--legend <layout> Draw the legend under the picture, beside it (vertical), or not at all (none) One of horizontal, vertical, none. Default horizontal.
--theme <theme> The ground the bitmap holds One of light, dark. Default dark.
--out <file.png> required Write the PNG to this file
--scale <factor> Bitmap pixels per diagram pixel
--region <x,y,width,height> An exact region inside the diagram page
--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

Examples

Terminal window
archboard model rasterize --module Gateway --out gateway.png

Output

  • The canonical PNG receipt

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The selected flow is unavailable or missing

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model replay #

Render a recorded talk to a video file, frame by frame

  • Needs the server
  • Writes files

Synopsis

archboard model replay <talk> --out <file.mp4> [--theme <theme>] [--layout <engine>] [--url <url>]

Renders the picture of a talk that a recording kept to an MP4 or WebM file, chosen by the --out extension.

The talk directory holds

  • talk.json: the model as it was recorded and when each step and subtitle line came.
  • voice.wav: the voice.

How it renders

  • The Archboard server's own page draws each frame of the video in a private headless Chromium, in software at 1920x1080.
  • The command encodes the frames at 30 frames a second with the voice.
  • No Codex or voice is used, and the model need not exist.

So a talk can be rendered again

  • In the other theme with --theme.
  • With the other layout engine with --layout.
  • After a renderer fix.

Needs

  • A Chromium or Google Chrome executable on PATH or named by ARCHBOARD_RENDERER_CHROMIUM.
  • ffmpeg: the one named by ARCHBOARD_FFMPEG, else on PATH, else nixpkgs#ffmpeg-headless run through Nix.

Arguments

Argument What it does
<talk> required The talk's directory, as a recording wrote it
--out <file.mp4> required Where to write the video: a .mp4 or .webm file
--theme <theme> Which palette the pane draws in; the palette the talk was recorded in when absent One of light, dark.
--layout <engine> Which layout engine lays the model out; the engine the talk was recorded with when absent One of track, blocks.
--url <url> The Archboard server to talk to; overrides ARCHBOARD_URL Default http://127.0.0.1:4242.

Examples

Terminal window
archboard model replay ~/.local/state/archboard/recordings/20260930T101500Z-pipeline --out pipeline.mp4
archboard model replay ./pr-1234-talk --theme dark --out pr-1234-dark.webm

Output

  • The video that was written

Exit codes

Exit When
0 Success The command did what it said. Its output is above.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
4 RECORDER_UNAVAILABLE No Chromium or Google Chrome executable was found, or the one named could not start.
4 ENCODER_UNAVAILABLE No ffmpeg with the encoders the file needs (libx264 and aac for MP4, libvpx-vp9 and libopus for WebM) is on PATH or named by ARCHBOARD_FFMPEG, and Nix is not there to run nixpkgs#ffmpeg-headless, or running it failed. Checked before a browser starts, so nothing was started.
1 RENDER_FAILED The picture could not be rendered to a file: the page did not draw a frame in time, the browser stopped, or ffmpeg failed. No video was written and the talk was kept, to render again with model replay.

model config #

Discover the configured vocabulary or its editor schema

  • Reads only

Synopsis

archboard model config [--schema] [--url <url>] [-C <dir>]

Prints the vault policy, source path and current diagnostics. --schema emits a JSON Schema generated from the canonical YAML validation schema, without requiring a running server.

Arguments

Argument What it does
--schema Print the generated editor JSON Schema
--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

Examples

Terminal window
archboard model config
archboard model config --schema > config.schema.json

Output

  • The current interpreted vault policy and diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model schema #

List the JSON Schemas of the model files and requests, or print one

  • Reads only

Synopsis

archboard model schema [<name>]

Without a name, lists each schema's name and title. With a name, prints that JSON Schema, rendered from the validation of this installation.

Needs no server and no vault.

A valid shape is not yet valid architecture. A write also checks

  • Names.
  • Identities.
  • The claim.
  • The complete revision.

Arguments

Argument What it does
<name> The schema to print One of model-manifest, module, flows, model-initialize, model-edit, model-import, model-migrate, vault-config.

Examples

Terminal window
archboard model schema
archboard model schema model-edit

Output

  • The schema list, or one JSON Schema

Exit codes

Exit When
0 Success The command did what it said. Its output is above.

Refusals

It has no refusals of its own. The exit codes of every command apply.

model init #

Initialize an empty canonical planning model

  • Needs the server
  • Writes the model
  • Writes files

Synopsis

archboard model init --name <value> --operation-id <value> --writer <value> [--url <url>] [-C <dir>] --doing <line>

Creates one canonical model through the existing signed installation and recovery workflow. Existing models and legacy boards are never replaced.

In a Git checkout that has no vault, it needs no server. It first makes <root>/.archboard/vault with the default vocabulary, and registers the checkout.

Arguments

Argument What it does
--name <value> required The model name
--operation-id <value> required The stable retry identity
--writer <value> required The author identity
--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> required One present-tense line saying what this write does, shown on every pane holding the model and never written to it

Examples

Terminal window
archboard model init --name Shop --operation-id initialize-shop --writer agent --doing 'Initialize architecture'

Output

  • Canonical initialization receipt or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable Private history setup cannot complete

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
1 DOING_REQUIRED A model write did not declare what it was doing.
2 VAULT_NOT_FOUND The working directory, or the directory -C names, is in no Git checkout. No enclosing <dir>/.archboard/vault exists. In a Git checkout that holds no vault, this command runs without one and is not refused. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model archive-init #

Explicitly initialize private history for an untracked vault

  • Needs the server
  • Writes the model

Synopsis

archboard model archive-init [--url <url>] [-C <dir>]

Creates a private bare archive outside source repositories. Returns its local directory for Git identity, signing and remote configuration. Sends no history. Existing source repositories are refused without changes.

Arguments

Argument 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

Examples

Terminal window
archboard model archive-init -C /tmp/architecture-notes

Output

  • Private archive setup or structured recovery diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable Private history setup cannot complete

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model export #

Export complete canonical inputs and retained history

  • Needs the server
  • Writes files

Synopsis

archboard model export [--out <file.json>] [--url <url>] [-C <dir>]

Writes a portable JSON bundle with exact architecture inputs and complete Git archive ancestry. Repository source files and private runtime state remain separate.

Arguments

Argument What it does
--out <file.json> Write the portable model bundle to this file
--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

Examples

Terminal window
archboard model export --out architecture.json

Output

  • The portable bundle file receipt or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the portable operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model import #

Import verified canonical inputs and complete history

  • Needs the server
  • Writes the model

Synopsis

archboard model import [--input <file.json>] [--url <url>] [-C <dir>]

Reads a complete request with bundle, expectedRevision, operationId, writer and doing. Installs into empty or identical authored inputs through the existing durable journal. Initialize private history first for an untracked vault.

The input follows the model-import schema.

Arguments

Argument What it does
--input <file.json> Read the complete import request from this file, or standard input when absent
--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

Examples

Terminal window
archboard model import --input import-request.json -C /tmp/restored-model

Output

  • The durable import receipt or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the portable operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model edit #

Edit canonical modules and independent flow behavior durably

  • Needs the server
  • Writes the model

Synopsis

archboard model edit [--input <file.json>] [--url <url>] [-C <dir>] --doing <line>

Reads expectedRevision, target, operationId, writer, claim and changes from JSON. Changes can edit modules, flows, or walkthroughs.

Proposal intents create, edit, reconcile, settle, adopt, or shelve states. Corrections name the previous checkpoint and immutable source revisions.

Deliberate inheritance removal or module recreation uses proposal.confirm. Forced adoption requires a fresh explicit comparison with current.

Supply the doing line through --doing. Retry the exact request after a lost response.

The input follows the model-edit schema.

Arguments

Argument What it does
--input <file.json> Read a JSON request from this file, or from standard input when absent
--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> required One present-tense line saying what this write does, shown on every pane holding the model and never written to it

Examples

Terminal window
archboard model edit --input edit.json --doing "explaining request routing" -C /tmp/shop

Output

  • The edit: the subjects it changed, the model revision before and after, and the checkpoint it made. A refusal carries diagnostics that say what to do.

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
1 DOING_REQUIRED A model write did not declare what it was doing.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model claim #

Claim canonical subjects and proposal states

  • Needs the server
  • Writes the model

Synopsis

archboard model claim [--input <file.json>] [--url <url>] [-C <dir>]

Reads target, writer, reason and subjects from JSON. Include the affected descendant states and existing subjects. A claim leaves the installation lock free between operations.

Arguments

Argument What it does
--input <file.json> Read a JSON request from this file, or from standard input when absent
--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

Examples

Terminal window
archboard model claim --input claim.json -C /tmp/shop

Output

  • The claim: its identity, its subjects and when it ends. A refusal carries diagnostics that say what to do.

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model release #

Release a canonical subject claim

  • Needs the server
  • Writes the model

Synopsis

archboard model release [--input <file.json>] [--url <url>] [-C <dir>]

Reads claim and writer from JSON. Only the writer that holds a claim can release it.

Arguments

Argument What it does
--input <file.json> Read a JSON request from this file, or from standard input when absent
--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

Examples

Terminal window
archboard model release --input release.json -C /tmp/shop

Output

  • The claims that remain. A refusal carries diagnostics that say what to do.

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model claims #

Read canonical subject claims

  • Needs the server
  • Reads only

Synopsis

archboard model claims [--url <url>] [-C <dir>]

Returns the active claims of this checkout, including their writer, reason and start time.

Arguments

Argument 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

Examples

Terminal window
archboard model claims -C /tmp/shop

Output

  • The active claims of this checkout. A refusal carries diagnostics that say what to do.

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model recover #

Recover the checkout's durable canonical edit

  • Needs the server
  • Writes the model

Synopsis

archboard model recover [--url <url>] [-C <dir>]

Resumes the recorded operation without creating another intent. Foreign inputs and a changed branch block replay. Keep those bytes and restore the logged context before retrying.

Arguments

Argument 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

Examples

Terminal window
archboard model recover -C /tmp/shop

Output

  • The operation that it finished, when one was pending. A refusal carries diagnostics that say what to do.

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model record #

Record one exact retained canonical walkthrough

  • Needs the server
  • Writes the model
  • Writes files

Synopsis

archboard model record --out <file.mp4> [--theme <theme>] [--layout <engine>] [--language <tag>] [--talk <dir>] --checkpoint <id> --walkthrough <id|name> [--url <url>] [-C <dir>]

Uses the existing local voice, talk storage, and frame renderer. Every beat reads the same retained checkpoint. Missing subjects refuse recording before voice starts.

Arguments

Argument What it does
--out <file.mp4> required Where to write the video: a .mp4 or .webm file
--theme <theme> Which palette the recording draws in One of light, dark. Default dark.
--layout <engine> Which layout engine lays the model out One of track, blocks. Default blocks.
--language <tag> The language of the narration, as a BCP 47 tag such as en, da or pt-BR Default en.
--talk <dir> Where to keep the talk (its steps and voice), which model replay renders again; a new directory in the state directory when absent
--checkpoint <id> required One exact retained checkpoint: list them with model checkpoints, or keep the current model with model retain
--walkthrough <id|name> required One walkthrough in that checkpoint, by id or name; model read lists the walkthroughs
--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

Examples

Terminal window
archboard model record --checkpoint <id> --walkthrough Tour --out tour.mp4

Output

  • The canonical recording receipt or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The retained walkthrough cannot be recorded

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model render #

Render a canonical architecture or behavioral reading

  • Needs the server
  • Writes files

Synopsis

archboard model render [--module <id>] [--state <id>] [--scope <id>] [--focus <id>] [--hide-kind <id>] [--expand <id>] [--flow <id>] [--grammar <grammar>] [--checkpoint <id>] [--theme <theme>] [--legend <layout>] --out <file.svg> [--url <url>] [-C <dir>]

The sequence and flowchart grammars require an explicit flow identity or unique name. The complete flow includes every participant, independently of module scope and structural filters.

Arguments

Argument What it does
--module <id> Select a module by identity or unique name
--state <id> Select an explicit architectural state
--scope <id> Open an exact module scope
--focus <id> repeatable Focus these identities
--hide-kind <id> repeatable Hide these relationship kinds
--expand <id> repeatable Open these modules beside the scope
--flow <id> One qualified flow identity or unique current or former name
--grammar <grammar> Draw sequence or flowchart One of architecture, sequence, flowchart.
--checkpoint <id> Read this exact retained checkpoint
--theme <theme> The standalone SVG theme One of auto, light, dark. Default auto.
--legend <layout> Draw the legend under the picture, beside it (vertical), or not at all (none) One of horizontal, vertical, none. Default horizontal.
--out <file.svg> required Write the self-contained SVG to this file
--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

Examples

Terminal window
archboard model render --flow 'Shop#Checkout' --grammar sequence --out request.svg

Output

  • The exact reading receipt or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The selected flow is unavailable or missing

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model snapshot #

Write a state and its comparison state to one portable file

  • Needs the server
  • Writes files

Synopsis

archboard model snapshot [--model <id>] [--state <id|name>] [--against <id|name>] [--flow <id>] --out <file.json> [--url <url>] [-C <dir>]

Writes one JSON file that holds everything needed to draw a state without an Archboard server: the model reading, the reading of its comparison state, the vault check with its policy and diagnostics, and the path data of the icons that the policy names. Share or archive the file to keep one reading of the model.

The selectors are those of model read. The format field names the version of the file format, and cliVersion the CLI that wrote it. An unchanged vault gives the same bytes.

Arguments

Argument What it does
--model <id> Require this exact model identity in the addressed vault
--state <id|name> Select current or a draft by stable identity or unique current or former name
--against <id|name> Compare against one explicit state or complete checkpoint identity
--flow <id> Select one flow by qualified identity or unique current or former name
--out <file.json> required Write the snapshot to this file
--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

Examples

Terminal window
archboard model snapshot --out model.snapshot.json
archboard model snapshot --state 'Queued fulfilment' --out queued.snapshot.json

Output

  • The written snapshot's receipt or structured diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested model or module is unavailable. The result carries affected paths, identities and recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model locality #

Rank modules by how often their code changes, and find modules that change together

  • Needs the server
  • Reads only

Synopsis

archboard model locality [--state <state>] [--checkpoint <checkpoint>] [--against <against>] [--since <since>] [--url <url>] [-C <dir>]

Reads the selected state against the local Git history of every repository its modules bind.

It answers

  • Which modules are hotspots, with the most commits in the period.
  • Which pairs are coupled: they changed in the same commits, in at least 5 shared commits and 30% of their own.

It also names the modules it could not read and why. Source refs stay local and no source history is retained.

Arguments

Argument What it does
--state <state> Read this draft by identity or name; current when absent
--checkpoint <checkpoint> Read this exact retained checkpoint instead of a live state
--against <against> Read the state beside this one, so the answer says what a plan joins
--since <since> Start the period at this date, or at a date and time with offset; a year before each HEAD when absent
--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

Examples

Terminal window
archboard model locality

Output

  • Canonical revision and source analysis evidence

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The selected canonical architecture is unavailable
2 unread A repository could not read the base or head that was named

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model footprint #

Compare a source branch with the architecture: which modules its commits changed

  • Needs the server
  • Reads only

Synopsis

archboard model footprint [--state <state>] [--checkpoint <checkpoint>] [--against <against>] [--base <base>] [--head <head>] [--model-at <head|checkout>] [--fail-outside] [--fail-preexisting] [--url <url>] [-C <dir>]

Reads the commits between --base and HEAD in every repository the selected state binds, and answers which modules they changed.

A module counts as changed only when its bound code differs between the merge base and HEAD. A change that a later commit undoes, or that a merge brings in from a lower layer of a stack, does not count. Each changed module lists the commits that changed it.

With a draft selected, it sets those against the draft

  • Planned and changed.
  • Changed outside the plan.
  • Planned but unchanged.

Each changed module lists, in holds, the other changed modules bound inside it, because a module bound to a directory changes with each of them. It lists them only when they bind each file that the branch changed in its own binding. A module that holds another is not counted as changed outside the plan.

It also lists, in unboundFiles, each changed file that no module is bound to, because no module shows that change. The files of the vault are not listed.

With a draft selected, it also lists, in preexisting, each module that the draft adds and whose bound code the branch does not add. Its code was there at the merge base, or its binding names code that exists nowhere. A picture of the draft marks such a module as added, although the diff shows no new code for it.

The branch adds code to a module when it adds a file inside its binding that the merge base lacks, or, for a binding to a declaration, the declaration. A module bound to a directory that the branch adds a file to is therefore not preexisting. A renamed file adds no code. Each module says in newSource whether the branch added code to it.

With --fail-outside, it exits 1 when the branch changed a module that the draft does not name. A module bound to a directory passes when each file it changed lies in the binding of another changed module inside it. If the branch also changed a file that only the outer module binds, the outer module fails. A file that no module is bound to never fails it. A gate before a merge uses it.

With --fail-preexisting, it exits 1 when preexisting names a module. Model code that exists at the base in the current state first, and repair a binding whose code exists nowhere.

With --head, the selected state is read from the vault as the repository that holds the vault has it at that head, without a checkout. A head that only a code repository has leaves the vault on disk. --model-at checkout reads the vault on disk, for a gate that runs where the draft was just edited. The answer's vaultRead names the vault it read.

A repository that cannot read the base or head is named, and the command exits 2. Source refs stay local and no source history is retained.

Arguments

Argument What it does
--state <state> Read this draft by identity or name; current when absent. It names a draft of the vault that this command reads: with --head, the vault at that head, unless --model-at checkout
--checkpoint <checkpoint> Read this exact retained checkpoint instead of a live state
--against <against> Read the draft beside this state; its base or current when absent
--base <base> The Git ref the branch started from, such as main (required)
--head <head> The Git ref the commits run up to; the HEAD of each checkout when absent
--model-at <head|checkout> head (default) reads the vault as the repository that holds it has it at --head, so the head's own drafts and bindings count; checkout reads the vault on disk. With no --head, or a head that only a code repository has, it reads the vault on disk
--fail-outside Exit 1 when the branch changed a module that the draft does not name. It needs a draft from --state
--fail-preexisting Exit 1 when the draft adds a module whose bound code the branch does not add. It needs a draft from --state
--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

Examples

Terminal window
archboard model footprint --base main

Output

  • Canonical revision and source analysis evidence

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The selected canonical architecture is unavailable
2 unread A repository could not read the base or head that was named
1 outside With --fail-outside, the branch changed a module that the draft does not name
1 preexisting With --fail-preexisting, the draft adds a module whose bound code the branch does not add

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model explain #

Explain a captured architecture reading through the local agent

  • Needs the server
  • Writes the model

Synopsis

archboard model explain [--input <file.json>] [--url <url>] [-C <dir>]

Reads an invocation with its tab session, exact revision, subjects, and reading intent. latest discovers the last action in the tab. The read, retry and cancel actions use the original action identity and vault. Answers stay temporary.

Arguments

Argument What it does
--input <file.json> Read the action from JSON or standard input when absent
--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

Examples

Terminal window
archboard model explain --input explanation.json -C /tmp/shop

Output

  • The captured request, progress, answer, or refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The action is unavailable or refused

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model read #

Read an authored canonical module model

  • Needs the server
  • Reads only

Synopsis

archboard model read [<module>] [--legacy-address <address>] [--bookmark <id|name>] [--walkthrough <id|name>] [--shared] [--preview <origin>] [--references] [--reference <index>] [--code] [--model <id>] [--state <id|name>] [--against <id|name>] [--compare] [--flow <id>] [--checkpoint <id>] [--url <url>] [-C <dir>]

Returns ordered root modules, authored details, source-owned relationships, and the exact input revision. A module selector accepts a qualified id or unique name.

Use these for legacy data

  • --preview <origin>: the saved legacy mapping plan.
  • --state <qualified-original-id>: one original model state.
  • --checkpoint <id>: retained originals.

Legacy authority stays unchanged.

Use --walkthrough <id|name> for pinned narrative playback. --shared requires an exact retained playback target.

Arguments

Argument What it does
<module> A qualified module id or a unique name
--legacy-address <address> Follow an exact original address from an installed migration map or explicit preview
--bookmark <id|name> Select one content-free imported bookmark from an installed migration map or preview
--walkthrough <id|name> Resolve one narrative against one complete revision
--shared Require an exact retained playback target
--preview <origin> Preview the saved legacy mapping plan for this import namespace
--references Resolve explicit foreign model references without changing either model
--reference <index> Follow this zero-based reference index on the selected module
--code Resolve code for the selected module through existing checkout selection
--model <id> Require this exact model identity in the addressed vault
--state <id|name> Select current or a draft by stable identity or unique current or former name
--against <id|name> Compare against one explicit state or complete checkpoint identity
--compare Include the default whole-state semantic comparison
--flow <id> Select one flow by qualified identity or unique current or former name
--checkpoint <id> Read one complete immutable checkpoint identity
--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

Examples

Terminal window
archboard model read
archboard model read 'Shop#Gateway' -C /tmp/shop

Output

  • The coherent model or structured diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested model or module is unavailable. The result carries affected paths, identities and recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model inspect #

Read one module's interface or one group's boundary

  • Needs the server
  • Reads only

Synopsis

archboard model inspect [<module>] [--group <id>] [--state <id|name>] [--checkpoint <id>] [--url <url>] [-C <dir>]

Reports what the model claims about one module or one group, read over the whole state before any reading narrows it. The answer holds counts and lists, and never a score.

A module with parts answers with its interface and a count of each of these

  • The entry points: the parts that relationships from outside reach, with those relationships.
  • The hidden parts: the parts that none reaches.
  • The callers: the modules outside where those relationships start.
  • The outgoing relationships.
  • The pass-through entry points: a question about each, never a fault.

It also lists the relationships that end on the module itself: each makes a caller and no entry point. A module with no parts answers that it holds no parts.

A group answers with

  • Its members.
  • The relationships between them.
  • The relationships that cross its boundary, with their direction.
  • The modules at the far end.

A configured group that no module joined answers empty.

Arguments

Argument What it does
<module> A qualified module id or a unique name. Name this or --group
--group <id> The configured group id whose boundary to read Required when unless a module is named instead.
--state <id|name> Select current or a draft by stable identity or unique current or former name
--checkpoint <id> Read one complete immutable checkpoint identity
--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

Examples

Terminal window
archboard model inspect 'Order store'
archboard model inspect 'Shop#Gateway' --state 'Queued fulfilment' -C /tmp/shop
archboard model inspect --group fulfillment

Output

  • The module or the group as it stands in the selected reading

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested model or module is unavailable. The result carries affected paths, identities and recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 UNKNOWN_GROUP The vault configures no group with this id. The refusal lists the configured ids.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model proposals #

List compact proposals and current state metadata

  • Needs the server
  • Reads only

Synopsis

archboard model proposals [--url <url>] [-C <dir>]

Lists the active proposals and every retained state of the model: current, draft, historical and shelved. Each one comes with its identity, name, summary, predecessor, baseline and lifecycle.

The --state selector of the other model commands takes one of these identities or names.

Arguments

Argument 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

Examples

Terminal window
archboard model proposals
archboard model proposals -C ../platform

Output

  • The coherent model or structured diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested model or module is unavailable. The result carries affected paths, identities and recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model compare #

Compare coherent canonical architectural states

  • Needs the server
  • Reads only

Synopsis

archboard model compare [<module>] [--legacy-address <address>] [--bookmark <id|name>] [--walkthrough <id|name>] [--shared] [--preview <origin>] [--references] [--reference <index>] [--code] [--model <id>] [--state <id|name>] [--against <id|name>] [--compare] [--flow <id>] [--checkpoint <id>] [--beside <id|name>] [--url <url>] [-C <dir>]

Reads the selected state with its comparison. The selectors are those of model read.

Interface changes come first, on standard error and in the comparison. An interface change costs every caller, and a change inside a module costs one module.

The interface measures of each state follow side by side, as counts that are never combined and rank no state.

The comparison also lists every stable subject. Use --beside for a competing proposal that is not the base.

Arguments

Argument What it does
<module> A qualified module id or a unique name
--legacy-address <address> Follow an exact original address from an installed migration map or explicit preview
--bookmark <id|name> Select one content-free imported bookmark from an installed migration map or preview
--walkthrough <id|name> Resolve one narrative against one complete revision
--shared Require an exact retained playback target
--preview <origin> Preview the saved legacy mapping plan for this import namespace
--references Resolve explicit foreign model references without changing either model
--reference <index> Follow this zero-based reference index on the selected module
--code Resolve code for the selected module through existing checkout selection
--model <id> Require this exact model identity in the addressed vault
--state <id|name> Select current or a draft by stable identity or unique current or former name
--against <id|name> Compare against one explicit state or complete checkpoint identity
--compare Include the default whole-state semantic comparison
--flow <id> Select one flow by qualified identity or unique current or former name
--checkpoint <id> Read one complete immutable checkpoint identity
--beside <id|name> repeatable Another state whose interface measures go beside these two
--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

Examples

Terminal window
archboard model compare --state 'Queued fulfilment'
archboard model compare --state 'One index' --beside 'Entry per job'

Output

  • The selected state with its comparison, or structured diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested model or module is unavailable. The result carries affected paths, identities and recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model retain #

Retain exact current architecture or original migration inputs locally

  • Needs the server
  • Writes the model

Synopsis

archboard model retain [--migration <origin>] [--expected-plan <digest-or-none>] --operation-id <id> --writer <name> --expect-revision <digest> [--dependency <checkpoint>] [--url <url>] [-C <dir>] --doing <line>

Uses configured Git identity and signing without changing current files, index or HEAD.

Repeat the same operation identity and request to recover the same checkpoint. Required dependencies are complete checkpoint identities.

Migration retention names --migration and --expected-plan. Use none for an absent plan. The expected source revision comes from model inventory.

Arguments

Argument What it does
--migration <origin> Retain original legacy inputs under this import namespace
--expected-plan <digest-or-none> The exact saved mapping revision, or none when no plan exists
--operation-id <id> required The stable identity for this retention intent
--writer <name> required The agent retaining the reading
--expect-revision <digest> required The exact input digest returned by model read
--dependency <checkpoint> repeatable Retain a required baseline through actual Git ancestry; repeat for several
--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> required One present-tense line saying what this write does, shown on every pane holding the model and never written to it

Examples

Terminal window
archboard model retain --operation-id capture-1 --writer agent --expect-revision <digest> --doing 'retaining the reviewed reading' -C /tmp/shop

Output

  • The saved local checkpoint or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable Retention failed without changing current architecture

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
1 DOING_REQUIRED A model write did not declare what it was doing.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model checkpoints #

List retained local architecture checkpoints

  • Needs the server
  • Reads only

Synopsis

archboard model checkpoints [--url <url>] [-C <dir>]

Lists immutable checkpoint identities and source associations. Archive synchronization records never become architectural states. Current files are not read.

Arguments

Argument 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

Examples

Terminal window
archboard model checkpoints -C /tmp/shop

Output

  • Local checkpoints or structured recovery diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The local archive cannot be read

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model inventory #

Inventory original legacy boards and identity evidence

  • Needs the server
  • Reads only

Synopsis

archboard model inventory --origin <id> [--url <url>] [-C <dir>]

Returns exact source fingerprints, complete original coverage, aliases, identity evidence, conflicts and a separate mapping plan. The origin is a stable short namespace chosen by the owner. This read changes no files.

Arguments

Argument What it does
--origin <id> required The owner's stable one-to-eight-character import namespace
--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

Examples

Terminal window
archboard model inventory --origin Shop -C /tmp/shop

Output

  • Original inputs and explicit mapping choices

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The inventory or mapping record is unavailable. The answer includes recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model publication #

Read explicit archive publication status

  • Needs the server
  • Reads only

Synopsis

archboard model publication <checkpoint> [--url <url>] [-C <dir>]

Reads durable local evidence for one exact checkpoint without contacting a remote. Ordinary source pushes never establish archive publication.

Arguments

Argument What it does
<checkpoint> required A complete immutable checkpoint identity
--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

Examples

Terminal window
archboard model publication <checkpoint> -C /tmp/shop

Output

  • Publication status or structured recovery diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested history operation cannot complete

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model publication-configure #

Configure an explicit archive publication destination

  • Needs the server
  • Writes the model

Synopsis

archboard model publication-configure --remote <name> --ref <refs/heads/archive> [--url <url>] [-C <dir>]

Saves an existing named Git remote and a full archive ref privately. Reports the remote retention-policy limitation without publishing architecture.

Arguments

Argument What it does
--remote <name> required The explicitly configured Git remote name
--ref <refs/heads/archive> required The complete independent archive branch ref
--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

Examples

Terminal window
archboard model publication-configure --remote archive --ref refs/heads/archboard-history -C /tmp/shop

Output

  • Publication status or structured recovery diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested history operation cannot complete

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model publish #

Publish complete retained architecture history

  • Needs the server
  • Writes the model

Synopsis

archboard model publish <checkpoint> --remote <name> --ref <refs/heads/archive> [--url <url>] [-C <dir>]

Publishes the configured archive closure without force-pushing. A stale push fetches and joins signed archive ancestry without merging architectural content. Network failure leaves durable local work intact.

Arguments

Argument What it does
<checkpoint> required A complete immutable checkpoint identity
--remote <name> required The explicitly configured Git remote name
--ref <refs/heads/archive> required The complete independent archive branch ref
--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

Examples

Terminal window
archboard model publish <checkpoint> --remote archive --ref refs/heads/archboard-history -C /tmp/shop

Output

  • Publication status or structured recovery diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested history operation cannot complete

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model fetch #

Fetch complete archive history for a missing reading

  • Needs the server
  • Writes the model

Synopsis

archboard model fetch <checkpoint> --remote <name> --ref <refs/heads/archive> [--url <url>] [-C <dir>]

Fetches the configured named archive ref and its complete ancestry, including shallow-clone dependencies. Current architecture, index and source HEAD remain unchanged.

Arguments

Argument What it does
<checkpoint> required A complete immutable checkpoint identity
--remote <name> required The explicitly configured Git remote name
--ref <refs/heads/archive> required The complete independent archive branch ref
--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

Examples

Terminal window
archboard model fetch <checkpoint> --remote archive --ref refs/heads/archboard-history -C /tmp/shop

Output

  • Publication status or structured recovery diagnostics

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The requested history operation cannot complete

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model migrate #

Install an owner-authorized complete migration preview

  • Needs the server
  • Writes the model

Synopsis

archboard model migrate [--input <file.json>] [--url <url>] [-C <dir>]

Read a complete migration request with source, plan, candidate, destination and checkout fingerprints. Retain exact originals and install through the existing durable journal. Every converted current or draft beat requires an explicit original view.

The input follows the model-migrate schema.

Arguments

Argument What it does
--input <file.json> Read the complete import request from this file, or standard input when absent
--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

Examples

Terminal window
archboard model migrate --input migration-request.json -C /tmp/shop

Output

  • The durable import receipt or structured refusal

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The runtime refused the portable operation and supplies recovery instructions

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

model plan #

Save explicit legacy identity mappings and conflict choices

  • Needs the server
  • Writes the model

Synopsis

archboard model plan [--input <file.json>] [--url <url>] [-C <dir>] --doing <line>

Reads {plan, expectedPlan} from JSON and saves only .archboard/migration-plan.json. Source and plan fingerprints refuse stale choices. Legacy boards remain the active architecture. No canonical composition or cutover occurs.

Arguments

Argument What it does
--input <file.json> A JSON planning request; standard input when absent
--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> required One present-tense line saying what this write does, shown on every pane holding the model and never written to it

Examples

Terminal window
archboard model plan --input choices.json --doing "Record the owner identity choices" -C /tmp/shop

Output

  • The inventory with saved planning choices

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
2 unavailable The inventory or mapping record is unavailable. The answer includes recovery actions.

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
1 DOING_REQUIRED A model write did not declare what it was doing.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.
Docs

Type to search every page, command and schema.