Configuration File

All persistent settings live in one JSON file, written by bb auth login and bb config set. 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
authMethod	"basic" | "oauth"	Active authentication method	bb auth login
username	string	Your Bitbucket username (API token auth)	bb auth login -u
apiToken	string	Your API token (API token auth)	bb auth login -p
oauthAccessToken	string	OAuth access token	bb auth login (OAuth)
oauthRefreshToken	string	OAuth refresh token	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	bb auth login --client-secret
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
lastVersionCheck	string	Timestamp of last update check	Automatic

Example configuration (OAuth)

{
  "authMethod": "oauth",
  "oauthAccessToken": "xxxxxxxxxxxxxxxx",
  "oauthRefreshToken": "xxxxxxxxxxxxxxxx",
  "oauthExpiresAt": 1711036800,
  "defaultWorkspace": "myworkspace"
}

Example configuration (API token)

{
  "authMethod": "basic",
  "username": "myuser",
  "apiToken": "ATBB_xxxxxxxxxxxxxxxxxxxx",
  "defaultWorkspace": "myworkspace",
  "skipVersionCheck": false,
  "versionCheckInterval": 7
}

---

Managing configuration

View all settings

bb config list

Output:

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

KEY               VALUE
----------------  -----------
username          myuser
defaultWorkspace  myworkspace
apiToken          ********
skipVersionCheck  false

Settable keys: defaultWorkspace, skipVersionCheck, versionCheckInterval, prCreateIncludeDefaultReviewers. 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 four 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
skipVersionCheck	boolean	bb config set skipVersionCheck true
versionCheckInterval	integer (days, ≥ 1)	bb config set versionCheckInterval 7
prCreateIncludeDefaultReviewers	boolean	bb config set prCreateIncludeDefaultReviewers true

skipVersionCheck and prCreateIncludeDefaultReviewers accept only true or false. versionCheckInterval accepts only positive integers (>= 1).

Readable keys

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

username, defaultWorkspace, skipVersionCheck, versionCheckInterval, prCreateIncludeDefaultReviewers

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 -p
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.

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 API token, 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 authentication credentials (OAuth tokens or API token) but keeps defaultWorkspace and other settings. For OAuth, it also revokes the token on Bitbucket’s side.

Full reset

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.