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,
initasks which of those on thePATHto 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,
initasks whether Claude Code or Codex, whichever is on thePATH, 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,
initassumes that an agent runs it. Its answer ends with that prompt innext. 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
archboard initarchboard init --repo ~/Projects/paymentsOutput
- 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
archboard repo listrepo 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
archboard repo listOutput
- 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
gitlists for it. - The first known checkout of a repository becomes the one read for it. Adding another never changes that, and
repo usedoes.
An untracked vault
- Outside any Git checkout, a directory that holds
.archboard/vaultis 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
renamedin the answer gives that name.
Arguments
| Argument | What it does |
|---|---|
<dir>
|
Directory; the working directory when absent |
Examples
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
archboard repo use ../payments-worktreeOutput
- 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
archboard repo forget ../payments-worktreeOutput
- 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 --stdioof the checkout's own TypeScript 7 or later. typescript-language-serverfor 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
archboard repo language-serverarchboard repo language-server rust scripts/rust-analyzerarchboard repo language-server rust nix --arg=develop --arg=--command --arg=rust-analyzerarchboard repo language-server c clangdarchboard repo language-server go goplsarchboard repo language-server python pyright-langserver --arg=--stdioarchboard repo language-server typescript typescript-language-server --arg=--stdio --globalarchboard repo language-server swift --removeOutput
- 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
archboard telemetryarchboard telemetry offarchboard telemetry onOutput
- 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.