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.
--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	Show full values in table output without truncating long cells.
--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.
-h, --help	boolean	—	Print help for the command.
-V, --version	boolean	—	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.

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 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'

--no-truncate

Show table cells in full. By default, long values (pull request descriptions, comment bodies, branch names) are truncated to keep rows on one line. --no-truncate disables that for the current invocation:

bb pr comments list 42 --no-truncate

The truncation suffix is the three ASCII characters ... and it counts against the column budget, so a 50-character cap yields 47 characters plus .... --no-truncate affects table output only — JSON payloads are never truncated, so passing it alongside --json does nothing.

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

List-command flags

--limit and --all are options on list commands, not global flags. bb pr view --limit 5 fails with error: 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, so --limit 200 makes four round trips. Values below 1 fail with --limit must be a positive integer.

--all

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

Both flags are available on these twelve commands:

• bb repo list
• bb pr list
• bb pr activity
• bb pr comments list
• bb snippet list
• bb snippet comments list
• bb pipeline list
• bb commit list
• bb status list
• bb workspace list
• bb project list

bb pr checks, bb pr reviewers list, bb repo default-reviewers list and bb config list are single-request and accept neither. 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.

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 — and 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