> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepitboard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files and environment variables

> pitboard keeps its files in `~/.pitboard`, parked logins in the keychain or a vault, and reads these environment variables.

The paths shown are defaults that [environment variables](/reference/files#environment-variables) can move.

## The pitboard directory

pitboard's directory is `~/.pitboard`, or the path in `PITBOARD_HOME`. The command line and the app share it.

pitboard creates each directory at mode 0700 and each file at 0600, except those in `backups/`. An existing directory keeps its mode.

pitboard refuses a directory whose path contains `Dropbox`, `Google Drive`, `OneDrive`, `com~apple~CloudDocs` or `Sync`, because parked logins belong to one machine.

| File            | Holds                                                                                                                                                                                                                                                                                                                                                                 | Written by                                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `state.json`    | The enrolled accounts: label, tool, email address, account identifiers, and each parked login's name and expiry                                                                                                                                                                                                                                                       | Every change pitboard makes, and renewals |
| `state.lock`    | The lock that lets one change or renewal run at a time                                                                                                                                                                                                                                                                                                                | Every change pitboard makes, and renewals |
| `journal.json`  | The record of a switch while it runs. An interrupted switch leaves it behind, and the next change pitboard makes finishes or undoes it; see [Interrupted switches](/concepts/switching#interrupted-switches).                                                                                                                                                         | A switch                                  |
| `pending`       | Names of parked logins about to be written, one per line. If a run is killed midway, the next change pitboard makes finds each login by its name here. Absent when there are none.                                                                                                                                                                                    | Switches, sign-ins and renewals           |
| `signin.lock`   | The lock that allows one sign-in at a time                                                                                                                                                                                                                                                                                                                            | A sign-in                                 |
| `signin/`       | The config directory a tool is given during a sign-in, so the login in use is left alone. Removed when the sign-in ends, or by the next sign-in if pitboard was stopped during one.                                                                                                                                                                                   | A sign-in                                 |
| `vault/`        | Linux only: parked logins, one file each                                                                                                                                                                                                                                                                                                                              | Switches, sign-ins and renewals           |
| `usage.json`    | The newest usage reading for each account                                                                                                                                                                                                                                                                                                                             | Reading usage, and the status line        |
| `usage.lock`    | The lock around `usage.json` and `sessions.json`                                                                                                                                                                                                                                                                                                                      | Reading usage, and the status line        |
| `readings/`     | One file per account, with 14 days of readings, to work out how long the account lasts                                                                                                                                                                                                                                                                                | Reading usage                             |
| `asking.json`   | When pitboard last asked Anthropic or OpenAI for each account's usage, and how long to wait before asking again                                                                                                                                                                                                                                                       | Reading usage                             |
| `sessions.json` | The usage each Claude Code session last gave `pitboard statusline`, and the account in use then. A session not seen for 7 days is dropped.                                                                                                                                                                                                                            | The status line                           |
| `backups/`      | Copies of Claude Code's config from before each switch rewrote it. Each is named after the time it was made, in seconds since 1 January 1970, such as `claude.json.1790000000`. The 10 newest are kept. They hold no login, but do hold your email address and the path of each project Claude Code has opened. Each keeps the mode of Claude Code's file.            | A Claude Code switch                      |
| `audit.log`     | One tab-separated line per change or renewal: the time, `cli` or `app` for where it was made, the verb such as `use`, the subject and the outcome. It holds no email address, and holds an account id only in a `reclaim` line with the outcome `discarded`, whose subject is a parked login's name. [`pitboard log`](/reference/maintenance-commands#log) prints it. | Every change pitboard makes, and renewals |
| `audit.log.1`   | The previous `audit.log`, moved aside once it passed 256 KiB                                                                                                                                                                                                                                                                                                          | Every change pitboard makes, and renewals |

Only files in `vault/` and `signin/` can hold a login. To delete the directory, see [Remove pitboard](/install/remove#delete-parked-logins-and-pitboards-files).

## Parked logins

On macOS, each parked login is an item in your default keychain, named `pitboard-park-<account id>-<time>`. Its keychain account is the one Claude Code's item uses, usually your user name from `USER`.

`<account id>` is a Claude Code account's Anthropic UUID or, for OpenAI's Codex CLI, is built from the account's ChatGPT ids. `<time>` is when the login was parked or last renewed, in milliseconds since 1 January 1970.

On Linux, each parked login is a file in `~/.pitboard/vault/`, named `pitboard-park-<account id>-<time>.json`.

For why parked logins are kept there, see [Security and privacy](/security#where-parked-logins-are-kept).

## Claude Code and Codex files

| Path                                    | What pitboard does with it                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.claude.json`                        | Reads the account the file records as in use. After a Claude Code switch, copies it to `backups/` and writes the incoming account into it. A `~/.claude/.config.json`, where one exists, is used instead.                                                                                                                                                                                                                             |
| Keychain item `Claude Code-credentials` | macOS: the Claude Code login in use. A switch reads and replaces it. With `CLAUDE_CONFIG_DIR` set, the name ends in `-` and 8 hex characters from a hash of the directory's path.                                                                                                                                                                                                                                                     |
| `~/.claude/.credentials.json`           | Linux: the Claude Code login in use. macOS: Claude Code's fallback when a keychain write fails, which pitboard reads after the keychain item.                                                                                                                                                                                                                                                                                         |
| `~/.claude/.storage-write.lock`         | The lock Claude Code takes around each write of its login. pitboard takes it during a switch.                                                                                                                                                                                                                                                                                                                                         |
| `~/.claude/settings.json`               | Read for `apiKeyHelper`, and for an `env` block that sets `CLAUDE_CODE_CUSTOM_OAUTH_URL` or a variable that overrides Claude Code's login, listed in [Environment variables](/reference/files#environment-variables). Managed settings are read too: `managed-settings.json` and `managed-settings.d/*.json` in `/Library/Application Support/ClaudeCode` on macOS or `/etc/claude-code` on Linux. A project's settings are not read. |
| `~/.codex/auth.json`                    | The Codex login in use. A switch reads and replaces it.                                                                                                                                                                                                                                                                                                                                                                               |
| `~/.codex/config.toml`                  | Read for `cli_auth_credentials_store`. For the values pitboard refuses, see [Use pitboard with Codex](/guides/codex#before-you-enrol-a-codex-account).                                                                                                                                                                                                                                                                                |

For how a switch changes these files, see [How switching works](/concepts/switching#what-a-switch-does).

## Renewal schedule

`pitboard schedule install`, or turning on **Renew parked logins daily** in **Settings** > **General**, writes these files. `pitboard schedule uninstall`, or turning it off, removes them. So does `pitboard uninstall` when pitboard's directory is `~/.pitboard`.

| Item    | macOS                                                                                                                                                                               | Linux                                                                                                                                 |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Files   | `~/Library/LaunchAgents/com.datlechin.pitboard.renew.plist`                                                                                                                         | `~/.config/systemd/user/pitboard-renew.service` and `~/.config/systemd/user/pitboard-renew.timer`, even when `XDG_CONFIG_HOME` is set |
| Name    | launchd label `com.datlechin.pitboard.renew`                                                                                                                                        | unit `pitboard-renew.timer`                                                                                                           |
| Program | The `pitboard` that installed it, by the path it was started with, such as Homebrew's link, so an upgrade does not break it. From the app: `Pitboard.app/Contents/Helpers/pitboard` | The `pitboard` that installed it, by the path it was started with, such as Homebrew's link, so an upgrade does not break it           |
| Runs    | `<program> renew`                                                                                                                                                                   | `<program> renew`                                                                                                                     |
| When    | Once a day, first a day after it is written: `StartInterval` 86400, `RunAtLoad` false                                                                                               | Once a day: `OnUnitActiveSec=86400`, `OnStartupSec=900`                                                                               |

## The app

The app is `Pitboard.app`, with the bundle identifier `com.usepitboard.Pitboard`.

| Path inside `Pitboard.app`                                                         | What it is        |
| ---------------------------------------------------------------------------------- | ----------------- |
| `Contents/Helpers/pitboard`                                                        | The command line  |
| `Contents/Resources/man/pitboard.1`                                                | The man page      |
| `Contents/Resources/completions/pitboard.bash`, `pitboard.zsh` and `pitboard.fish` | Shell completions |

The app stores these keys in `~/Library/Preferences/com.usepitboard.Pitboard.plist`:

| Key                                | Holds                                                                                             |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `hasBeenSeen`                      | Whether the app has opened its window at first launch                                             |
| `secondAccountDeclined`            | The tools for which you clicked **Not Now** when the **Accounts** pane suggested a second account |
| `menuBarShows`                     | **Menu bar shows**: `nameAndUsage`, `usage` or `icon`                                             |
| `settingsTab`                      | The Settings tab shown last: `general`, `commandLine` or `updates`                                |
| Keys of Sparkle, the app's updater | Its update settings and when it last checked                                                      |

macOS keeps **Open pitboard at login** as a login item, outside this file. The app's files can also be in `~/Library/Application Support`, `~/Library/Caches` and `~/Library/HTTPStorages`, named after `com.usepitboard.Pitboard`. To remove them, see [Remove pitboard](/install/remove#remove-pitboard-itself).

## Environment variables

Opened from Finder, the app does not see your shell's variables, so the defaults apply. Daily renewal runs with the scheduler's environment, not your shell's.

| Variable                                                                                                                                                                                                                                                     | Read by      | Effect                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HOME`                                                                                                                                                                                                                                                       | Both         | Your home directory, the `~` in every path here.                                                                                                                                                                                                                                                                           |
| `PITBOARD_HOME`                                                                                                                                                                                                                                              | Both         | pitboard's directory, in place of `~/.pitboard`. Daily renewal always renews `~/.pitboard`.                                                                                                                                                                                                                                |
| `PITBOARD_NO_ARGV`                                                                                                                                                                                                                                           | Both         | On macOS, when it is `1`, pitboard refuses to write a large login on `security`'s argument line, and does not renew a parked login it could not write back. A renewal schedule installed while it is set keeps it. See [Large logins on macOS](/security#large-logins-on-macos).                                           |
| `PITBOARD_API_BASE`                                                                                                                                                                                                                                          | Command line | For pitboard's tests. Sends the requests meant for Anthropic and OpenAI to this URL, if it is an `http` URL whose host is a loopback IP address, such as `http://127.0.0.1:8080`.                                                                                                                                          |
| `CLAUDE_CONFIG_DIR`                                                                                                                                                                                                                                          | Both         | Claude Code's config directory, in place of `~/.claude`. The config file becomes `$CLAUDE_CONFIG_DIR/.claude.json`, and the keychain item's name gets a suffix. Empty counts as unset.                                                                                                                                     |
| `CLAUDE_SECURESTORAGE_CONFIG_DIR`                                                                                                                                                                                                                            | Both         | The directory that picks Claude Code's keychain item, `.credentials.json` and lock, in place of the config directory. Set but empty, it picks `~/.claude` and `Claude Code-credentials`.                                                                                                                                   |
| `USER`                                                                                                                                                                                                                                                       | Both         | macOS: the keychain account of Claude Code's item and of parked logins. Unset or empty, your login name is used. A name with characters other than letters, digits, `.`, `_` and `-` becomes `claude-code-user`.                                                                                                           |
| `CLAUDE_CODE_CUSTOM_OAUTH_URL`                                                                                                                                                                                                                               | Command line | Not empty: pitboard refuses every change to a Claude Code account, and refuses `repair`, `uninstall` and `abandon`, with the error `custom_oauth_endpoint`. Claude Code then keeps its login under a name pitboard does not read. The command line and the app also read it from an `env` block in Claude Code's settings. |
| `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_GATEWAY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, `CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD` | Command line | Any of these not empty: Claude Code uses something other than the login pitboard switches. Changes to Claude Code accounts warn with `auth_overridden`, and `pitboard doctor` warns. The command line and the app also read these, and `apiKeyHelper`, from Claude Code's settings.                                        |
| `CODEX_HOME`                                                                                                                                                                                                                                                 | Both         | Codex's directory, in place of `~/.codex`. Empty counts as unset.                                                                                                                                                                                                                                                          |
| `PATH`                                                                                                                                                                                                                                                       | Command line | Where the command line looks for `claude` and `codex`, which it runs to sign in. Only absolute directories are searched.                                                                                                                                                                                                   |
| `NO_COLOR`                                                                                                                                                                                                                                                   | Command line | Not empty: no colour in any output. `pitboard statusline` also drops its colour when `NO_COLOR` is set but empty.                                                                                                                                                                                                          |
| `PITBOARD_CLAUDE`, `PITBOARD_CODEX`                                                                                                                                                                                                                          | App          | The path of the `claude` or `codex` program the app runs to sign in, in place of the one it finds.                                                                                                                                                                                                                         |
