GitHub

Install and set up

Put the archboard CLI on your machine, set a repository up with archboard init, and make sure that the server answers.

On this page

What you need#

  • Linux on x64 or arm64, or macOS on Apple silicon. Under Windows, use WSL 2.
  • Git, and a package manager to install the package: npm, pnpm, Yarn or Bun.
  • A Codex sign-in for the agent dock, voice, narration and recordings. The map, the checks and the pictures work without it.
  • Chromium or Chrome only for PNG pictures and recordings. SVG pictures need no browser.

Install the CLI#

The package is archboard on npm. @archboard/cli is the same program under a second name. Pick your package manager:

npm install --global archboardarchboard --version

The package manager installs only the build for your platform. The install puts archboard on your PATH.

Set up a repository#

Run archboard init in the repository that you want to map:

Terminal window
cd ~/Projects/payments-api
archboard init
  1. It installs the skills. archboard writes and reads models. archboard-pr gives a pull request an architecture explainer. archboard-plan carries a proposal through the to-spec, to-tickets and implement-spec skills. Codex gets them, and Claude Code gets them when claude is on the PATH.
  2. It makes the vault. The vault is .archboard/vault at the root of the checkout. The model takes the name of the repository directory.
  3. It registers the checkout. The browser then lists it, and bindings into this repository resolve here.
  4. It hands the language servers to an agent. At a terminal, init asks whether Claude Code or Codex sets them up. The agent shows its plan and waits for your consent. Without a terminal, the JSON answer ends with next, the prompt for the agent.

Commit the vault with your code. A reviewer then reads a change to the architecture in the same diff as the change to the code.

Terminal window
git add .archboard
git commit -m "docs(architecture): add the Archboard vault"

Set up the language servers#

A language server knows where code defines a name. With one, archboard check code resolves a name to its definition, and only resolved evidence can make a warning. A match by name only stays information.

  1. Find the languages that the repository uses.

  2. Install a server for each language that has no default. TypeScript 7 and later needs none.

  3. In the checkout, register each server:

    Terminal window
    archboard repo language-server python pyright-langserver --arg=--stdio
  4. Commit .archboard/language-servers.json with the vault. Every machine and every CI run then uses the same servers. Each machine still needs the server programs: install them in CI as The check as a gate shows.

Start the server#

Every command that needs the server starts it when nothing answers. To start it yourself, run:

Terminal window
archboard start
archboard status

A release server listens on http://archboard.localhost:4242. Chrome and Firefox send every *.localhost name to this machine with no setup. The CLI connects to 127.0.0.1:4242. Set ARCHBOARD_NO_AUTOSTART=1 to stop the autostart.

Make sure that it works#

Terminal window
archboard model read
archboard check

model read prints the model as JSON. A new vault holds an empty planning model, which is a model with no current state yet. archboard check exits 0 on a new vault.

Find the vault from another directory#

A command finds its vault the way Git finds its repository. Inside a checkout, the vault is .archboard/vault at the checkout root. -C <dir> starts the search in another directory:

Terminal window
archboard -C ~/Projects/payments-api model read

If the root has no vault, the command refuses with exit 2, and its error says how to make one. The refusal names each known vault whose models bind this repository, as the -C to give.

Update and remove#

Run the install command again, then restart the server so that it runs the new version. Until then, every command warns that the server runs another version.

Terminal window
npm install --global archboard@latest
archboard restart

There is no uninstall command. To remove Archboard, stop the server and remove the package:

Terminal window
archboard stop
npm uninstall --global archboard

Then delete the skill directories, such as ~/.agents/skills/archboard, ~/.agents/skills/archboard-pr and ~/.agents/skills/archboard-plan, and the state directory. The state directory holds the Codex sign-in, the registry of checkouts and the logs. On Linux it is ~/.local/state/archboard, and on macOS it is ~/Library/Application Support/archboard. Keep each vault that you still need: it is in its repository, not in the state directory.

INSTALL.md covers builds from a clone, Nix, every language server, recordings, machine state and macOS.

Docs

Type to search every page, command and schema.