Configuration File

The Bitbucket CLI stores configuration in a JSON file. This page documents the file format, location, and available settings.

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
username	string	Your Bitbucket username	bb auth login
apiToken	string	Your API token (stored securely)	bb auth login
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

Example Configuration

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

---

Managing Configuration

View All Settings

bb config list

Output:

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

Key              Value
username         myuser
apiToken         ********
defaultWorkspace myworkspace

Note

The API token is masked for security. Use bb auth token to see the actual token.

Get a Specific Value

bb config get defaultWorkspace
# Output: myworkspace

Set a Value

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

Typed key validation:

• skipVersionCheck accepts only true or false
• versionCheckInterval accepts only positive integers (>= 1)

Values are stored as native JSON types, so bb config get <key> --json returns booleans/numbers for these keys.

Example:

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

Protected Keys

Some configuration keys cannot be set directly:

Key	Reason	How to Set
username	Tied to authentication	Use bb auth login
apiToken	Security-sensitive	Use bb auth login

---

Update Notifications

The CLI automatically checks for updates when you run the bare bb command (without any subcommands). This helps you stay current with the latest features and bug fixes.

How It Works

• Checks npm registry for the latest version
• Compares with your installed version
• Shows a notification if an update is available
• Caches the check result for 24 hours (configurable)
• Skips checks in CI environments automatically

Example Notification

⚠ A new version is available: 1.5.0 (you have 1.4.0)
  Run 'bun install -g @pilatos/bitbucket-cli' to update
  Or disable with 'bb config set skipVersionCheck true'

Disable Notifications

To permanently disable update notifications:

bb config set skipVersionCheck true

Change Check Frequency

To check less frequently (e.g., once per week):

bb config set versionCheckInterval 7

Tip

The versionCheckInterval value is in days. Set it to a higher number if you prefer fewer interruptions.

---

Configuration Precedence

When determining workspace and repository, the CLI checks sources in this order:

1. Command-line flags (highest priority)

   bb pr list -w otherworkspace -r otherrepo

2. Git repository remote (if in a git repo)

   cd /path/to/cloned-repo
   bb pr list  # Uses workspace/repo from git remote

3. Configuration file (lowest priority)

   bb config set defaultWorkspace myworkspace
   bb pr list  # Uses config default

See Understanding Repository Context for detailed examples.

---

File Permissions

The configuration file contains sensitive data (API token). The CLI sets appropriate permissions automatically:

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

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 username and apiToken but keeps defaultWorkspace and other settings.

It does not perform a full config reset.

Full Reset

Delete the configuration file entirely:

macOS / Linux

rm ~/.config/bb/config.json

Windows

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

Then re-authenticate:

bb auth login

---

Troubleshooting

”Cannot read config file”

The file may be corrupted. Delete and recreate it:

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

“Cannot write config file”

Check directory permissions:

ls -la ~/.config/bb/

Create the directory if it doesn’t exist:

mkdir -p ~/.config/bb

Config Not Being Used

Verify the CLI is reading from the expected location:

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

Remember that command-line flags and git context take precedence over config file settings.