Config Commands

Manage CLI configuration settings.

Global options available on all config commands: --json [fields], --jq <expression>, --no-color, --no-unicode, --locale <locale>. See Global flags for the full list.

Configuration file

Configuration is stored in a JSON file at:

• Linux/macOS: ~/.config/bb/config.json (fixed path — XDG_CONFIG_HOME is not read)
• Windows: %APPDATA%\bb\config.json, falling back to %USERPROFILE%\AppData\Roaming\bb\config.json

On Linux and macOS the CLI creates the directory 0700 and the file 0600, and refuses to run if either grants group or other access. See Configuration file for the permission rules and how to fix them.

Available settings

Key	bb config get	bb config set	Description
defaultWorkspace	yes	yes	Default workspace for commands
skipVersionCheck	yes	yes	Disable update notifications (default: false)
versionCheckInterval	yes	yes	Days between update checks (default: 1)
prCreateIncludeDefaultReviewers	yes	yes	Auto-add the repository’s default reviewers on bb pr create (default: false)
username	yes	no — use bb auth login	Bitbucket username
apiToken	no — use bb auth token	no — use bb auth login	Bitbucket API token (masked in bb config list)
aliases	no — use bb alias	no — use bb alias	User-defined command aliases
lastVersionCheck	no	no	Timestamp of the last update check. Auto-managed; bb config get lastVersionCheck fails with Unknown config key

bb auth login also writes authMethod — basic for API tokens, oauth for OAuth — and, after an OAuth login, the oauth* keys (oauthAccessToken, oauthRefreshToken, oauthExpiresAt, and custom consumer credentials). Only bb auth login and bb auth logout touch those keys; see Configuration file for the full schema.

Configuration file format

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

Don’t edit this file by hand. Use bb config set for settings, bb auth login for credentials, and bb alias for command aliases.

bb config get

Print a configuration value.

bb config get <key>

Readable keys: username, defaultWorkspace, skipVersionCheck, versionCheckInterval, prCreateIncludeDefaultReviewers. Any other key exits 1 with Unknown config key '<key>', except apiToken, which points you at bb auth token.

Examples

# Get default workspace
bb config get defaultWorkspace

# Get username
bb config get username

# Get output as JSON
bb config get defaultWorkspace --json

---

bb config set

Set a configuration value.

bb config set <key> <value>

Settable keys, and the values each accepts:

Key	Accepted values	Stored type
defaultWorkspace	Any string	string
skipVersionCheck	true or false	boolean
versionCheckInterval	Positive integer (>= 1), in days	number
prCreateIncludeDefaultReviewers	true or false	boolean

Examples

# Set default workspace
bb config set defaultWorkspace myworkspace

# Disable update notifications
bb config set skipVersionCheck true

# Check for updates weekly instead of daily
bb config set versionCheckInterval 7

# Get output as JSON
bb config set defaultWorkspace myworkspace --json

Values that don’t match the key’s type are rejected and exit 1:

bb config set skipVersionCheck maybe

✗ Invalid value for 'skipVersionCheck'. Expected 'true' or 'false'.

JSON output for typed keys:

{ "success": true, "key": "skipVersionCheck", "value": true }

Caution

bb config set username … and bb config set apiToken … are rejected outright:

✗ Cannot set 'username' directly. Use 'bb auth login' to configure authentication.

Use bb auth login for credentials.

---

bb config list

List all configuration values.

bb config list [options]

Examples

# List all config
bb config list

# List as JSON for scripting
bb config list --json

# Read one value out of the JSON
bb config list --json --jq '.config.defaultWorkspace'

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.

With an empty config file the table is replaced by ℹ No configuration set; the Config file: line and the Settable keys: footer still print.

apiToken is always masked. OAuth credentials are omitted from bb config list entirely — after an OAuth login the listing shows no auth rows at all.