JSON Output

All commands support the global --json flag.

Use JSON mode for automation, scripts, and CI/CD pipelines.

Quick Usage

# List pull requests as JSON
bb pr list --json

# Disable color formatting and return JSON
bb repo view --json --no-color

Output Model

JSON output is normalized, but not every command returns the same shape.

• List commands return an object envelope with metadata and an array.
• Read/create/update commands usually return a resource object (or resource plus metadata).
• Action commands usually return success: true plus identifiers.

Typical top-level metadata fields include:

• workspace
• repoSlug
• pullRequestId
• count

Common Examples

bb pr list --json

{
  "workspace": "myworkspace",
  "repoSlug": "myrepo",
  "state": "OPEN",
  "count": 2,
  "pullRequests": [
    {
      "id": 42,
      "title": "Add feature",
      "state": "OPEN"
    }
  ]
}

bb repo list --json

{
  "workspace": "myworkspace",
  "count": 1,
  "repositories": [
    {
      "full_name": "myworkspace/myrepo",
      "is_private": true
    }
  ]
}

bb pr diff 42 --stat --json

{
  "workspace": "myworkspace",
  "repoSlug": "myrepo",
  "pullRequestId": 42,
  "mode": "stat",
  "filesChanged": 3,
  "totalAdditions": 27,
  "totalDeletions": 11,
  "files": [
    {
      "path": "src/index.ts",
      "additions": 10,
      "deletions": 3
    }
  ]
}

bb pr diff 42 --web --json

{
  "workspace": "myworkspace",
  "repoSlug": "myrepo",
  "pullRequestId": 42,
  "mode": "web",
  "url": "https://bitbucket.org/myworkspace/myrepo/pull-requests/42/diff"
}

bb auth token --json

{
  "token": "base64-encoded-credentials"
}

jq Examples

# Print PR titles
bb pr list --json | jq -r '.pullRequests[].title'

# Count PRs
bb pr list --json | jq '.count'

# Get repository names
bb repo list --json | jq -r '.repositories[].full_name'

# Extract diff file paths
bb pr diff 42 --stat --json | jq -r '.files[].path'

Scripting Notes

• Prefer --json in scripts rather than parsing text output.
• Do not rely on text formatting symbols (✓, table separators, colors).
• If you need stable fields, prefer command-specific documented keys (pullRequests, repositories, files, success).

Errors

When a command fails, the CLI exits non-zero.

• In normal mode, errors are plain text on stderr.
• In --json mode, errors are compact JSON objects on stderr.

Example:

bb config get invalidKey --json 2>error.json
cat error.json
# {"name":"BBError","code":4003,"message":"Unknown config key 'invalidKey'. Valid keys: username, defaultWorkspace, skipVersionCheck, versionCheckInterval","context":{"key":"invalidKey"}}

In automation, always check the process exit code before parsing stdout JSON.