Configuration File

All persistent settings live in one JSON file, written by bb auth login, bb config set, and bb alias set. Logout and automatic OAuth refresh also update it. This page documents the file itself; for the commands that read and write it, see the Config command reference.

File location

macOS / Linux

~/.config/bb/config.json

Windows

%APPDATA%\bb\config.json

Typically: C:\Users\<username>\AppData\Roaming\bb\config.json

---

Configuration schema

Key	Type	Description	Set by
accounts	object	Saved accounts by name, see Account fields	bb auth login
activeAccount	string	Account used when neither --account nor BB_ACCOUNT is given	bb auth login, bb auth switch
credentialStorage	"file" | "keychain"	Where account secrets live (default: file)	bb config set
defaultWorkspace	string	Default workspace	bb config set defaultWorkspace
skipVersionCheck	boolean	Disable update notifications	bb config set
versionCheckInterval	number	Days between update checks (default: 1)	bb config set
prCreateIncludeDefaultReviewers	boolean	Auto-add the repository’s default reviewers on bb pr create (default: false)	bb config set
gitProtocol	"ssh" | "https"	Protocol for bb repo clone and fork fetches in bb pr checkout (default: ssh)	bb config set
aliases	object	User-defined command aliases	bb alias set
lastVersionCheck	string	Timestamp of last update check	Automatic

Account fields

Key	Type	Description	Set by
authMethod	"basic" | "oauth"	Authentication method of the account	bb auth login
username	string	Your Atlassian account email (API token auth)	bb auth login -u
apiToken	string	Your API token (API token auth); secret	bb auth login --with-token
oauthAccessToken	string	OAuth access token; secret	bb auth login (OAuth)
oauthRefreshToken	string	OAuth refresh token; secret	bb auth login (OAuth)
oauthExpiresAt	number	OAuth token expiry (Unix timestamp)	bb auth login (OAuth)
oauthClientId	string	Custom OAuth consumer client ID	bb auth login --client-id
oauthClientSecret	string	Custom OAuth consumer client secret; secret	bb auth login --client-secret
storage	"keychain"	Present when the secret fields live in the OS keychain instead	bb config set

Older versions of bb kept one account’s fields at the top level of the file. bb still reads those as the default account and moves them under accounts the first time it writes credentials, so upgrading needs no action.

Example configuration (two accounts)

{
  "accounts": {
    "default": {
      "authMethod": "basic",
      "username": "[email protected]",
      "apiToken": "ATBB_xxxxxxxxxxxxxxxxxxxx"
    },
    "personal": {
      "authMethod": "oauth",
      "oauthAccessToken": "xxxxxxxxxxxxxxxx",
      "oauthRefreshToken": "xxxxxxxxxxxxxxxx",
      "oauthExpiresAt": 1711036800
    }
  },
  "activeAccount": "default",
  "defaultWorkspace": "myworkspace",
  "versionCheckInterval": 7
}

Example configuration (keychain storage)

{
  "accounts": {
    "default": {
      "authMethod": "oauth",
      "oauthExpiresAt": 1711036800,
      "storage": "keychain"
    }
  },
  "activeAccount": "default",
  "credentialStorage": "keychain"
}

The tokens sit in the OS keychain under the service bitbucket-cli, one entry per account name. See Configuration storage.

---

Managing configuration

View all settings

bb config list

Output:

Config file: /Users/you/.config/bb/config.json

KEY               VALUE
----------------  -----------
username          [email protected]
defaultWorkspace  myworkspace
apiToken          ********
skipVersionCheck  false

Settable keys: defaultWorkspace, credentialStorage, skipVersionCheck, versionCheckInterval, prCreateIncludeDefaultReviewers, gitProtocol. Run 'bb config set --help' for details.

The API token is masked. Use bb auth token to see the real value.

Get a specific value

bb config get defaultWorkspace
# Output: myworkspace

Values are stored as native JSON types, so for the typed keys --json returns a real boolean or number rather than a quoted string:

bb config get skipVersionCheck --json
# {"key":"skipVersionCheck","value":true}

Set a value

bb config set defaultWorkspace myworkspace
bb config set skipVersionCheck true
bb config set versionCheckInterval 7

Settable keys

bb config set accepts these six keys; bb config list prints the current list as a footer. Everything else is written by bb auth login or by the CLI itself.

Key	Type	Example
defaultWorkspace	string	bb config set defaultWorkspace myworkspace
credentialStorage	file or keychain	bb config set credentialStorage keychain
skipVersionCheck	boolean	bb config set skipVersionCheck true
versionCheckInterval	integer (days, ≥ 1)	bb config set versionCheckInterval 7
prCreateIncludeDefaultReviewers	boolean	bb config set prCreateIncludeDefaultReviewers true
gitProtocol	ssh or https	bb config set gitProtocol https

skipVersionCheck and prCreateIncludeDefaultReviewers accept only true or false (case-insensitive, surrounding whitespace ignored). versionCheckInterval accepts only positive integers (>= 1). gitProtocol accepts only ssh or https (case-insensitive).

Readable keys

bb config get has its own allowlist, and it is not the same one:

username, defaultWorkspace, credentialStorage, skipVersionCheck, versionCheckInterval, prCreateIncludeDefaultReviewers, gitProtocol

username is readable but not settable; change it with bb auth login -u. bb config get apiToken refuses:

Cannot display 'apiToken' - it is part of your authentication credentials, not config. Use 'bb auth token' to retrieve credentials, or run 'bb config list' to see readable keys.

Any other key throws Unknown config key '<key>' with the valid list and a suggestion, e.g. (Did you mean defaultWorkspace?).

prCreateIncludeDefaultReviewers and the --default-reviewers flag

Config	Flag	Result
unset / false	(none)	Default reviewers are not added
true	(none)	Default reviewers are added
unset / false	--default-reviewers	Default reviewers are added
true	--no-default-reviewers	Default reviewers are not added

Protected keys

These keys cannot be set with bb config set:

Key	Reason	How to set
username	Tied to authentication	Use bb auth login -u
apiToken	Security-sensitive	Use bb auth login --with-token
authMethod	Managed by login flow	Use bb auth login
oauthAccessToken	Managed by OAuth flow	Use bb auth login
oauthRefreshToken	Managed by OAuth flow	Use bb auth login
oauthExpiresAt	Managed by OAuth flow	Use bb auth login

---

Update notifications

After every command the CLI checks npm for a newer version, at most once per versionCheckInterval days (default 1). The notice goes to stderr, and only when stderr is a TTY, so --json and piped output stay clean. It is skipped entirely in CI and when skipVersionCheck is true.

Example notification

──────────────────────────────────────────────────
A new version is available: <latest> (you have <current>)
  Run 'bun install -g @pilatos/bitbucket-cli' to update
  Or disable with 'bb config set skipVersionCheck true'
──────────────────────────────────────────────────

There is no warning glyph. The separator rules are 50 box-drawing dashes, or 50 ASCII hyphens under --no-unicode.

The update line follows where bb is installed: pnpm add -g for a pnpm global install, bun install -g for a Bun global install or bunx, a release download link for the standalone binary, and npm install -g for any other node_modules install. Outside node_modules, such as a source checkout, it suggests bun install -g.

Disable notifications

bb config set skipVersionCheck true

Change check frequency

versionCheckInterval is in days. Once per week:

bb config set versionCheckInterval 7

---

Configuration precedence

Command-line flags beat the git remote, which beats BB_WORKSPACE, which beats the config file:

bb pr list -w otherworkspace -r otherrepo   # flags win
cd /path/to/cloned-repo && bb pr list       # git remote
BB_WORKSPACE=myworkspace bb repo list       # env var
bb config set defaultWorkspace myworkspace  # config file

The full order, including which commands skip the git-remote step, is in Environment Variables. Understanding Repository Context has worked examples.

Some runtime behavior is tuned only with environment variables, not config keys; BB_HTTP_TIMEOUT for the API request timeout, for example.

---

File permissions

The config file holds your tokens (unless credentialStorage is keychain), so the CLI creates the directory 0700 and the file 0600, and writes atomically (temp file, then rename).

Platform	Directory	File
macOS/Linux	0700 (owner only)	0600 (owner read/write only)
Windows	Inherits user profile permissions	Inherits user profile permissions

On macOS and Linux the CLI also verifies both on every read. If any group or other bit is set, every command fails with error 4001 until you fix it:

Config file has insecure permissions (644); expected 600. Run: chmod 600 /Users/you/.config/bb/config.json
Config directory has insecure permissions (755); expected 700. Run: chmod 700 /Users/you/.config/bb

Windows skips the check, and a path that does not exist yet is not checked, so a fresh install never hits this.

Security

Never share your config file or commit it to version control. The API token grants access to your Bitbucket account.

---

Reset configuration

Clear authentication only

bb auth logout

This removes the current account’s credentials (OAuth tokens or API token) but keeps other accounts, defaultWorkspace and other settings. For OAuth, it also attempts to revoke the token on Bitbucket’s side.

Full reset

With keychain storage, run bb auth logout for each account first (or bb config set credentialStorage file), otherwise the keychain entries stay behind. Then delete the config file entirely:

macOS / Linux

rm ~/.config/bb/config.json

Windows

Remove-Item $env:APPDATA\bb\config.json

Then re-authenticate:

bb auth login

---

Troubleshooting

“Config file is not valid JSON”

Fix the file by hand, or delete it and log in again:

rm ~/.config/bb/config.json
bb auth login

“Config file has insecure permissions”

chmod 700 ~/.config/bb
chmod 600 ~/.config/bb/config.json

“Failed to read config file”

The path exists but is unreadable. Check ownership and permissions:

ls -la ~/.config/bb/

“Failed to write config file” / “Failed to create config directory”

The parent directory is missing or not writable:

mkdir -p ~/.config/bb
ls -ld ~/.config/bb

Config not being used

Verify the CLI is reading from the expected location:

bb config list
# Check the "Config file:" line

Command-line flags, git context and BB_WORKSPACE all take precedence over config file settings.