Commands

Run a command as pitboard <command>. The following table lists each <command> in the order of pitboard --help.

Command	Description	Page
`status`	What is signed in, and how much each account has left (the default)	Account commands
`enroll`	Add an account: the one signed in now, or with `--sign-in`, another one	Account commands
`use`	Switch a tool to an enrolled account	Account commands
`forget`	Drop an account and its parked login	Account commands
`abandon`	Give up on an interrupted switch that cannot be finished, keeping every login	Recovery commands
`repair`	Ask the credential store what parked logins are here, and account for every one	Recovery commands
`adopt`	Take over a pitboard directory another computer wrote, keeping the accounts	Recovery commands
`renew`	Renew every parked login that is due, and nothing else	Maintenance commands
`schedule`	Keep parked logins alive without running anything yourself	Maintenance commands
`log`	What pitboard has changed, and when	Maintenance commands
`uninstall`	Delete every parked login this pitboard wrote, the daily renewal schedule and pitboard’s own files	Maintenance commands
`rename`	Change the label an account is enrolled under	Account commands
`doctor`	Check that what pitboard relies on still holds on this machine	Maintenance commands
`statusline`	One line for Claude Code’s status bar; reads its session JSON on stdin	Integration commands
`completions`	Print a shell completion script	Integration commands
`help`	Print this message or the help of the given subcommand(s)	Global options
`manpage`	Print the man page	Integration commands

pitboard --help does not list manpage.

Default command

pitboard with no command runs pitboard status, and pitboard --json runs pitboard status --json. --offline and --fresh belong to status, so they need its name: pitboard status --offline.

Global options

Option	Description
`--json`	Machine-readable output: the same versioned JSON envelope for every command, whether it succeeds or fails
`-h, --help`	Print help
`-V, --version`	Print version

--json goes before or after the command: pitboard --json use work and pitboard use work --json are the same. For the fields of that JSON, see JSON output. Every command except help takes --help, and pitboard help <command> also prints a command’s help. pitboard --version prints the version, and no command takes --version. pitboard refuses a mistyped option or an extra word, as in pitboard status --verbose or pitboard status work, and exits with status 2.

Labels

A label names one account within its tool. work is a Claude Code account and codex/work is an account of OpenAI’s Codex CLI, so both tools can have a work.

A label can start with a tool prefix, claude/ or codex/, in lower case. claude/work always names the Claude Code account work.
Labels are compared exactly: Work and work are different labels.
A label is one word, with no spaces or control characters. Other characters, such as é or 工, are allowed. The only / in a label is the one after the prefix.

Commands read a bare label, one without a prefix, in two ways:

pitboard enroll reads a bare label as Claude Code. A Codex account needs the prefix, as in codex/work.
pitboard use, pitboard forget and the first label of pitboard rename look for a bare label in both tools. If both tools have it, the command fails and lists both labels with their prefix.

pitboard rename keeps an account in its tool: pitboard rename codex/work job gives codex/job. pitboard’s messages write a label the way a command takes it: work for Claude Code, codex/work for Codex, and claude/work where both tools have a work. pitboard refuses a label that breaks a rule, with one of these messages:

Rule broken	Message
A space or a control character in the label	a label must be one word, such as `personal` or `work`
A prefix that is not a tool	`codx` is not a tool pitboard knows. It knows: claude, codex
A prefix with no name	`codex/` names a tool but no account. Try `codex/work`
A second `/`	a label cannot contain `/`: it separates the tool from the name, so at most one belongs in `codex/a/b`
A bare label both tools have	`work` is enrolled for more than one tool: `claude/work`, `codex/work`. Say which one.
A rename into the other tool	`work` is a claude account, and a rename cannot move it to codex. Sign in to that tool and enrol the account there instead.

Output

A command prints its result on standard output. Errors go to standard error as error: <message>, and warnings as warning: <message>. With --json, pitboard prints one line of JSON on standard output, with any error or warning inside it. --help and --version print plain text even with --json. pitboard enroll --sign-in also writes to standard error: the line that starts Opening, and the tool’s own sign-in text. pitboard colours output that goes to a terminal, unless NO_COLOR is set and not empty. Output to a file or a pipe has no colour, and JSON output never has any. pitboard statusline keeps its colour through a pipe, because Claude Code reads the line from a pipe and draws those colours. Setting NO_COLOR, even to an empty value, turns that colour off. pitboard forget and pitboard uninstall print a question on standard error before they delete anything. They ask only when standard input and standard error are both terminals, and neither --yes nor --json is given. They go ahead on y, Y or yes.

Redirecting standard error, as in 2>/dev/null, also skips the question, and the command deletes without asking. Only signing in to the account again in a browser replaces a deleted parked login.

Exit codes

Code	Meaning
`0`	The command did what was asked.
`1`	A request could not be met, for example because the label is unknown or a service did not answer.
`2`	The command line was wrong: an unknown option, a missing argument, or a label for `pitboard enroll`, or the second label of `pitboard rename`, that breaks the label rules.
`3`	A login or a tool’s files are in a state pitboard will not act on, for example Codex signed in with an API key. `pitboard doctor` also exits 3 when a check fails.

Declining the question from pitboard forget or pitboard uninstall prints nothing more, changes nothing and exits 0. For the exit status of each error code, see Error and warning codes.

Get started

Install and remove

Use pitboard

Troubleshooting

How it works

Reference

Commands

Commands

Default command

Global options

Labels

Output

Exit codes

​Commands

​Default command

​Global options

​Labels

​Output

​Exit codes

Commands

Default command

Global options

Labels

Output

Exit codes