GitHub

Setup, checkouts and telemetry

Set a repository up for Archboard, tell this machine where each repository's checkout is, and turn usage telemetry on or off.

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

init #

Set this repository up for Archboard and hand its language servers to an agent

  • Writes files

Synopsis

archboard init [--repo <dir>]

Installs the archboard, archboard-pr and archboard-plan skills of this installation globally with the skills CLI (skills.sh). It installs them for Codex, and for Claude Code when claude is on the PATH.

The skills CLI is started by bun, pnpm or npx

  • At a terminal, init asks which of those on the PATH to use, or to skip.
  • Without a terminal, it uses the first one found, in that order.

Then init makes the repository's vault, <repo>/.archboard/vault, when it has none. It registers the checkout so that a browser lists it.

init removes a block that an earlier version wrote into CLAUDE.md or AGENTS.md. Nothing else in the file changes.

Last, the language servers. Choosing and installing them depends on the repository, so an agent sets them up.

What happens then depends on the terminal

  • At a terminal, init asks whether Claude Code or Codex, whichever is on the PATH, does it. It starts that agent in the repository with a prompt. The agent shows its plan and waits for your consent before it changes anything.
  • Without a terminal, init assumes that an agent runs it. Its answer ends with that prompt in next. The setup is not finished until the agent sets up the language servers.

Arguments

Argument What it does
--repo <dir> The repository to set up Default the git checkout that holds the working directory, else the working directory.

Examples

Terminal window
archboard init
archboard init --repo ~/Projects/payments

Output

  • What each step did, ending with the prompt for an agent when no agent was started

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.

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

Without a subcommand, archboard repo runs archboard repo list, and the options before the subcommand go to it.

Examples

Terminal window
archboard repo list

repo list #

List known repository checkouts and untracked vaults

  • Reads only

Synopsis

archboard repo list

Reads the machine-local checkout registry and lists

  • Every known checkout, with its repository identity, whether it is the chosen one for that identity, and whether its directory exists.
  • Every untracked vault, with its registry name.
  • The identities that have no chosen checkout.

Examples

Terminal window
archboard repo list

Output

  • Checkout registry

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.

repo add #

Register a repository checkout or an untracked vault

  • Writes files

Synopsis

archboard repo add [<dir>]

Registers a checkout, or an untracked vault, so that Archboard knows it. Every running server sees the change, so every tab lists it.

A Git checkout

  • The command derives the identity of the checkout from git. That identity is its origin remote, or with none the directory name of its main checkout.
  • Every worktree has the identity of its main checkout.
  • It records the local root of the checkout, with the worktrees that git lists for it.
  • The first known checkout of a repository becomes the one read for it. Adding another never changes that, and repo use does.

An untracked vault

  • Outside any Git checkout, a directory that holds .archboard/vault is registered as an untracked vault under its base name, made unique on this machine.
  • When a repository has the name of an untracked vault as its identity, the repository keeps that name.
  • The vault then gets the next free name, and renamed in the answer gives that name.

Arguments

Argument What it does
<dir> Directory; the working directory when absent

Examples

Terminal window
archboard repo add .

Output

  • Registry receipt

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.

repo use #

Choose the checkout that this machine reads for its repository

  • Writes files

Synopsis

archboard repo use [<dir>]

Makes the checkout the chosen one of its repository identity. The browser reads its vault, and a binding that another vault makes into that identity resolves there.

Registers the checkout, with its worktrees, when it is unknown. An untracked vault has no repository identity and is refused.

Every running server sees the change. So every pane that shows a model of the repository moves to this checkout with its model, and every tab lists it.

Arguments

Argument What it does
<dir> Directory; the working directory when absent

Examples

Terminal window
archboard repo use ../payments-worktree

Output

  • Registry receipt

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.

repo forget #

Forget a known checkout or untracked vault

  • Writes files

Synopsis

archboard repo forget <dir>

Removes the checkout or untracked vault at a directory from the machine-local registry. The directory need not exist.

Forgetting the chosen checkout of a repository that has other known checkouts leaves the repository with no chosen checkout until repo use.

Meanwhile its bindings resolve as unregistered, except from a vault inside one of its checkouts, which reads its own checkout.

Every running server sees the change, so every tab lists it.

Arguments

Argument What it does
<dir> required The directory of a known checkout or untracked vault

Examples

Terminal window
archboard repo forget ../payments-worktree

Output

  • Registry receipt

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.

repo language-server #

Show, set or remove the language servers of a repository or of this machine

  • Writes files

Synopsis

archboard repo language-server [<language>] [<command>] [--arg <argument>] [--remove] [--global] [--repo <identity>]

A language server resolves what the code check can only match by name. A repository names its servers in .archboard/language-servers.json at the root of its checkout.

Commit that file. Every machine and every CI run that has the checkout then uses the servers, with no setup.

The global language-servers.json beside the Archboard registry names a server for each language that the repository file leaves out.

The check runs exactly the command and its arguments, with the environment and PATH that the Archboard server started with. So the server runs code of the repository as an editor does.

In the repository file, a command with a / is a path from the checkout root. So the repository can commit a wrapper script that runs its server through nix, devenv or devbox.

The language is typescript, python, csharp, swift, c (C, C++ and Objective-C), rust or go. Python, C, C++, Objective-C, C#, Swift, Rust and Go have no default server.

A named TypeScript server wins.

Without one, the check runs

  • The native tsc --lsp --stdio of the checkout's own TypeScript 7 or later.
  • typescript-language-server for the checkout's TypeScript before 7.
  • Otherwise, when Archboard runs from a source checkout and not a release, Archboard's own TypeScript.

Without a language, the command shows both files. The checkout is the working directory's, unless --repo names a repository, which means its chosen checkout.

Arguments

Argument What it does
<language> One of typescript, python, csharp, swift, c, rust, go; without it, the command shows both files
<command> A program on the PATH, or a path to one; required with a language unless --remove is given
--arg <argument> repeatable An argument after the command; write one that starts with - as --arg=<argument>
--remove Remove the language's server instead of setting it
--global Write the global file of this machine, which every checkout falls back to, instead of the repository file
--repo <identity> The repository, such as github.com/acme/payments, whose chosen checkout holds the file; the working directory's checkout when absent

Examples

Terminal window
archboard repo language-server
archboard repo language-server rust scripts/rust-analyzer
archboard repo language-server rust nix --arg=develop --arg=--command --arg=rust-analyzer
archboard repo language-server c clangd
archboard repo language-server go gopls
archboard repo language-server python pyright-langserver --arg=--stdio
archboard repo language-server typescript typescript-language-server --arg=--stdio --global
archboard repo language-server swift --remove

Output

  • The repository file and the global file, with their servers after any change

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.

telemetry #

Show or change whether Archboard sends anonymous usage counts and error reports

  • Writes files

Synopsis

archboard telemetry [<setting>]

Archboard records each command and each unexpected error on this machine, and its server sends one usage event a day and one event for each error.

No event holds code, a module, file, repository or model name, a path, a prompt or an error message.

It is off in CI, in tests, when DO_NOT_TRACK is set, and when ARCHBOARD_TELEMETRY is 0. Turning it off deletes every record that waits to be sent.

Arguments

Argument What it does
<setting> Turn it on or off, or show its status (the default) One of on, off, status.

Examples

Terminal window
archboard telemetry
archboard telemetry off
archboard telemetry on

Output

  • Telemetry status

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.

Docs

Type to search every page, command and schema.