--json and --help, described in Global options. Exit statuses are as in Exit codes unless a section says otherwise.
A label such as codex/work names an account of OpenAI’s Codex CLI. pitboard enroll reads a bare label such as work as a Claude Code account. pitboard use, pitboard forget and the first label of pitboard rename look for a bare label in both tools.
A parked login is the login pitboard keeps for an account that is not in use. For more on both, see Labels and Parked logins.
status
status renews each parked login whose access token has expired or expires within 2 minutes. Then it asks about every account at the same time: Anthropic for Claude Code accounts, OpenAI for Codex accounts. Each request times out after 5 seconds.
An account asked about recently is not asked again until its numbers could have moved. For how long that takes, see How usage is read.
status shows Codex accounts only once one is enrolled. Until then, it reads none of Codex’s files and asks OpenAI nothing.
--offline renews nothing and writes nothing. It takes who is signed in from each tool’s own files, and each account says read without asking Anthropic or read without asking OpenAI.
--fresh asks again a service pitboard could not reach moments ago, but not one that asked pitboard to wait: those accounts keep their last numbers until the wait ends. Giving both options is refused with exit status 2.
status exits 0 even when a service cannot be reached, and the account’s last line says why. It exits 1 only when pitboard cannot load its account list.
To see the last numbers measured, without asking anyone:
--json output, see JSON output.
enroll
--sign-in, pitboard enroll records the account the tool is signed in to. It parks nothing: that account’s login is parked the first time you switch away from it.
With --sign-in, pitboard runs the tool’s own sign-in without touching the login in use. Before a browser opens, pitboard checks that it can load its account list and write where the tool keeps its login. It also checks that the tool’s program is on your PATH.
Only one sign-in runs at a time. While one runs, pitboard holds a lock on ~/.pitboard/signin.lock and refuses a second sign-in until the first finishes.
The sign-in runs in a private directory, ~/.pitboard/signin, which pitboard deletes and creates again, with mode 0700, before each sign-in. For Claude Code it runs claude auth login with CLAUDE_CONFIG_DIR set to that directory. For Codex it runs codex login with CODEX_HOME set to it.
When the sign-in finishes, pitboard reads the new login the tool stored. Codex, and Claude Code on Linux, store it in that directory. Claude Code on macOS stores it in a keychain item made for that directory.
pitboard then deletes the directory and, on macOS, the keychain item Claude Code created for that sign-in.
The
enrolled field of the --json output names what happened:
For a label not enrolled before,
in_use prints Enrolled work ([email protected]), the account signed in now. Its new login is the one in use. instead.
enroll enrols nothing if the account is already enrolled under another label (already_enrolled), or if the label names another account (label_taken).
If pitboard cannot tell whose login the tool is using, it parks the new login instead of putting it in use. It warns only when that label is the one it last recorded in use. For the warning and what to do, see Sign in to an account again.
To add a second Claude Code account:
--json output stays one line. When you finish signing in, pitboard prints:
use
pitboard use parks the login the label’s tool is using and puts the named account’s parked login in its place. The tool must be signed in to an enrolled account. The named account must have a parked login whose refresh token has not expired.
Before anything moves, pitboard checks that the parked login belongs to that account and that Anthropic or OpenAI still accepts it. If only its access token has expired, pitboard renews the parked login first. A switch therefore needs the network, for Claude Code and Codex alike.
If the account is already in use,
use prints work is already signed in. and moves no login.
After a switch, it prints Switched to work; personal is parked. and one more line. For Claude Code, that line is Claude Code sessions already running follow within 33 seconds. For Codex, it is the second line of the following example.
For every error a switch can end with, and what to do about each, see Error and warning codes.
To switch Codex to codex/work:
forget
pitboard forget drops an account from pitboard’s list. It deletes the account’s parked login, its last usage reading and its usage history. Deleting a parked login does not revoke it; see Security and privacy.
forget refuses the account in use, and its message says to switch to another account first. It reads which account is in use from the tool’s own files, so it needs no network.
At a terminal, without
--yes or --json, forget asks first on standard error:
old without being asked:
rename
pitboard rename changes only the label. The account keeps its parked login and its usage history, because pitboard files both under the account’s id, not its label. An account in use stays in use.
A rename stays inside the account’s tool:
pitboard rename codex/work job gives codex/job. pitboard refuses a <TO> that another account of that tool already has. Naming the other tool in <TO>, as in pitboard rename work codex/work, fails with exit status 2: