Global Flags

These flags are accepted by every bb command; the same set bb --help prints. --limit and --all look global but are not; see List-command flags.

Quick reference

Flag	Type	Default	Description
--json [fields]	optional CSV	off	Emit machine-readable JSON. Pass a comma-separated field list to project the output.
--jq <expression>	string	off	Run the JSON output through an in-process jq filter. Requires --json everywhere except bb api.
--raw-output	boolean	off	Print --jq string results without JSON quotes, like jq -r. Requires --jq.
--lean	boolean	off	Trim every links map in JSON output to its web URL (links.html). Requires --json everywhere except bb api.
--no-color	boolean	colors on	Disable ANSI colors. Also honoured: NO_COLOR, FORCE_COLOR.
--no-unicode	boolean	Unicode on	Use ASCII fallbacks for separators, arrows, and status icons. Also honoured: BB_NO_UNICODE.
--no-truncate	boolean	off	Print every table cell in full instead of fitting the table to the terminal width.
--no-input	boolean	off	Never prompt, even in an interactive terminal (except bb completion install, see --no-input). Also honoured: BB_PROMPT_DISABLED.
--locale <locale>	BCP-47	system	Locale for date/time formatting (e.g. de-DE, ja-JP). Falls back to BB_LOCALE, then LC_TIME/LC_ALL/LANG, then en-US.
-w, --workspace <workspace>	string	git remote / env / config	Override the workspace.
-r, --repo <repo>	string	git remote	Override the repository.
--account <name>	string	active account	Use this saved account. Also honoured: BB_ACCOUNT.
-h, --help	boolean	n/a	Print help for the command.
-V, --version	boolean	n/a	Print the CLI version.

The positive forms --color, --unicode and --truncate are also accepted, even though bb --help does not list them. Only --color changes anything; see Precedence summary.

bb help <command> is equivalent to bb <command> --help and works at every depth (bb help pr, bb help pr comments). The root Commands: list does not show help, but it is there. Every subcommand’s help lists these flags under Global Options:. A group run without a subcommand (bb pr) prints its help and exits 0.

Output flags

--json [fields]

Switch a command to JSON output. With no argument, the full response is printed. Pass a comma-separated field list to project to just those keys:

bb pr list --json
bb pr list --json id,title,state

JSON mode also disables spinners, colors, and progress notes so the output is safe to pipe. JSON is pretty-printed on a terminal and compact (one line) when stdout is a pipe or a file.

--json takes an optional value, so a bare --json swallows the next plain token. Put it after the subcommand:

bb pr list --json           # correct
bb --json=id,title pr list  # correct; the '=' form swallows nothing
bb --json pr list           # error 5002

The last one fails with --json consumed 'pr' as its field list, so 'list' was parsed as a top-level command.; rendered as a JSON envelope, since --json was set. The other global flags are not position-sensitive in this way.

--jq <expression>

Filter the JSON output through a jq expression. The filter runs in-process via the embedded jq engine, so you don’t need the jq binary installed. Requires --json:

bb pr list --json --jq '.pullRequests[] | select(.state == "OPEN") | .title'

bb api is the one exception. Its output is already JSON, so it takes --jq on its own:

bb api /repositories/my-ws --jq '.values[].name'

Everywhere else, --jq without --json fails with --jq requires --json (error 8002), printed as plain text on stderr rather than as a JSON envelope.

Field projection runs before jq and drops the wrapper key, so when you combine --json <fields> with --jq the filter sees a flat array; start it with .[], not .pullRequests[]:

bb pr list --json id,title --jq '.[] | .title'

--raw-output

Print string results from --jq as plain text instead of JSON strings, like jq -r. Requires --jq:

bb pr list --json --jq '.pullRequests[].title' --raw-output

--lean

Trim Bitbucket’s links maps, which make up most of a list payload, down to the web URL (links.html). Requires --json, except in bb api:

bb pr list --json --lean

See Lean output.

--no-truncate

On a terminal, tables are fitted to the window width. Long titles, descriptions, messages and comment bodies shrink and end in ...; ids, hashes, UUIDs and URLs keep their full width. A column never shrinks below 10 characters, so on a very narrow terminal rows wrap instead. --no-truncate turns the fitting off and prints every cell in full:

bb pr comments list 42 --no-truncate

When stdout is not a terminal (piped or redirected), tables are printed as tab-separated values: one line per row, no header, no padding and nothing cut off, so bb pr list | cut -f2 gives the full titles. Date columns are relative on a terminal (3 hours ago) and ISO 8601 when piped. The “Showing N results” hint goes to stderr. JSON is never truncated, so --no-truncate does nothing with --json.

--no-color and --no-unicode

--no-color disables ANSI colors. --no-unicode swaps Unicode separators and status glyphs for plain ASCII equivalents; useful for log aggregators that mangle Unicode, or terminals that don’t render the symbols cleanly.

Colors switch off on their own when stdout is not a TTY, so piping to a file already gives you plain text. Unicode does not: bb pr list > out.txt still writes the ─ separator rules, → branch arrows and ✓/✗/○ status glyphs. Pass --no-unicode or set BB_NO_UNICODE if you need ASCII in a redirect.

Tables themselves are already ASCII; the header underline is plain - characters and there are no vertical bars or outer border, so --no-unicode does not change the table frame.

The two environment variables are not symmetric:

• NO_COLOR triggers on any value, including the empty string. Both FORCE_COLOR (any value except 0) and a literal --color in argv override it.
• BB_NO_UNICODE triggers on any non-empty value and cannot be overridden per command. --unicode is accepted but has no effect while BB_NO_UNICODE is set; unset the variable instead.

Write-command flag

--dry-run

Commands that change something on Bitbucket accept --dry-run. The command runs as usual up to its first write request (POST, PUT, PATCH or DELETE), prints that request instead of sending it, and exits 0. Read requests it needs along the way, such as looking up a user or the current pull request, still go out. Confirmation prompts and the --yes gate are skipped, because nothing is changed.

$ bb pr decline 42 --dry-run
ℹ Dry run: this request was not sent.
POST https://api.bitbucket.org/2.0/repositories/myworkspace/myrepo/pullrequests/42/decline

The body follows the URL when the request has one, pretty-printed as JSON. Multipart uploads list their fields, with files shown by name and size. Credential-like keys (password, secret, token, …) are redacted in the body and the URL query. When a command would send several writes, only the first is shown. With --json the output is { "dryRun": true, "request": { "method", "url", "body" } }; see JSON output.

--dry-run is available on bb api and on every command that writes: repo create, repo delete, repo default-reviewers add|remove, repo downloads upload|delete, pr create, pr edit, pr merge, pr approve, pr unapprove, pr request-changes, pr decline, pr ready, pr comments add|edit|delete|reply|resolve|unresolve, pr reviewers add|remove, snippet create|edit|delete|watch|unwatch, snippet comments add|edit|delete, pipeline run|stop, status set, project create, webhook create|delete, branch-restriction create|delete, ssh-key add|delete and gpg-key add|delete. Commands that only change local files (auth, config, alias, completion, repo clone, pr checkout) do not accept it.

Prompt flag

--no-input

A few commands ask for what is missing when you run them in an interactive terminal:

• Destructive commands (bb repo delete, bb repo default-reviewers remove, bb repo downloads delete, bb pr comments delete, bb snippet delete, bb snippet comments delete, bb webhook delete, bb branch-restriction delete, bb ssh-key delete, bb gpg-key delete) name what they are about to change and ask Continue? (y/N) instead of failing without --yes.
• bb pr create asks for the title, and then an optional description, when --title is missing.
• bb auth login asks whether to use the browser (OAuth) or an API token when no auth flag is given, and asks for a missing Atlassian account email or token.

Prompts only appear when stdin and stdout are both terminals. Piped input, redirected output, --json, --no-input and a non-empty BB_PROMPT_DISABLED each switch them off, and the command then behaves exactly as it does in a script: a missing --yes or --title is an error, and bb auth login with no token fails with 1001 AUTH_REQUIRED instead of opening a browser. --json alone still lets a person in a terminal finish a browser login.

bb completion install is the exception. Its shell question comes from the completion installer and ignores all of these switches; see bb completion install.

bb repo delete myworkspace/old-repo            # asks Continue? (y/N)
bb repo delete myworkspace/old-repo --yes      # never asks
bb repo delete myworkspace/old-repo --no-input # fails: Use --yes to confirm.

Answering anything other than y or yes, or pressing Ctrl+C or Ctrl+D at a prompt, stops the command with error 5004 PROMPT_CANCELLED and nothing is changed. Ctrl+C exits with status 130, the rest with 1.

List-command flags

--limit and --all are options on list commands, not global flags. bb pr view --limit 5 fails with ✗ unknown option '--limit'.

--limit <n>

Cap the number of items returned. The default is 25 on every list command.

This caps items, not pages. The CLI fetches up to 50 items per request and keeps paging until the cap is met or no next page remains. Short pages and client-side filtering can require more requests. Values below 1 fail with --limit must be a positive integer.

--all

Fetch every page. --all overrides --limit.

Both flags are available on these commands:

• bb repo list
• bb repo ls
• bb repo downloads list
• bb pr list
• bb pr activity
• bb pr comments list
• bb snippet list
• bb snippet comments list
• bb pipeline list
• bb deployment list
• bb deployment environments
• bb branch-restriction list
• bb ssh-key list
• bb gpg-key list
• bb commit list
• bb status list
• bb workspace list
• bb project list
• bb search code
• bb webhook list

bb pr checks reads every page and bb pr reviewers list, bb repo default-reviewers list and bb config list are single-request; none of them accepts these flags. bb api uses --paginate instead.

When --limit cuts a table short, the CLI prints a hint:

Showing 25 pull requests. Use --limit <n> or --all to see more.

That hint is table output only. Under --json nothing is printed, so compare the envelope’s count against your limit yourself.

Context flags

-w, --workspace and -r, --repo

Override the workspace and repository for the current command:

bb pr list -w myworkspace -r myrepo

Repository-scoped commands fall back to the git remote of the current directory. Workspace-only commands never look at git; they resolve --workspace, then BB_WORKSPACE, then defaultWorkspace, and fail with No workspace specified. if none is set. That covers bb workspace view, every bb project and bb snippet command, bb repo list, bb repo create, bb repo clone, and bb api when it fills a {workspace} placeholder. Being inside a Bitbucket clone is not enough for those.

The full order is in Environment Variables, with worked examples in Understanding Repository Context.

Account flag

--account <name>

Run one command as another saved account without changing the active one:

bb --account personal pr list
BB_ACCOUNT=personal bb pr list   # same, for a whole shell or CI job

The flag beats BB_ACCOUNT, which beats the account picked with bb auth switch. On bb auth login it names the account to create or re-authenticate. See Multiple accounts.

Locale flag

--locale <locale>

Pin a BCP-47 locale tag for date/time formatting. This affects every human-readable date the CLI prints; PR timestamps, activity entries, comment dates. JSON output is locale-independent.

bb pr list --locale de-DE
bb pr view 42 --locale ja-JP

If --locale is unset, the CLI walks BB_LOCALE, then the POSIX locale variables in the order LC_TIME → LC_ALL → LANG, then falls back to en-US. Note that LC_TIME is checked before LC_ALL, which is the reverse of the usual POSIX override order; if you set both, LC_TIME wins here.

Values are normalised before use: a .UTF-8 codeset or @euro modifier suffix is stripped, _ becomes -, and C / POSIX map to en-US. An invalid BCP-47 tag never errors; it silently falls back to en-US.

Precedence summary

For settings that can come from multiple sources, the order is usually:

1. Command-line flag
2. Environment variable
3. Config file
4. Built-in default

Two documented exceptions: FORCE_COLOR beats --no-color, and --unicode cannot override BB_NO_UNICODE.

Color has one more wrinkle. --color is the highest-precedence color input of all, ahead of FORCE_COLOR, --no-color and NO_COLOR. It is matched by a raw scan of argv. So bb pr diff 42 --color never turns global color on even though it leaves the diff body uncolored, because bb pr diff takes --color <when> with the choices auto, always and never.

See also

• Environment Variables; env-var equivalents and precedence
• JSON Output; schema, field projection, scripting tips
• Configuration File; persistent settings