Auth commands

Use the authentication guide for setup. These commands accept the global flags.

Each command acts on the current account: --account <name>, else BB_ACCOUNT, else the active account (default until you add another). See Multiple accounts.

`bb auth login`

bb auth login [options]

In an interactive terminal, choose OAuth or an API token. Outside one, token flags or BB_API_TOKEN select API-token authentication, and anything else fails fast with 1001 instead of opening a browser.

The --username flag, BB_USERNAME variable, and stored username key keep their existing names for compatibility.

Options

Option	Description
`-u, --username <username>`	Atlassian account email for API tokens; selects token auth
`-p, --password <password>`	API token; selects token auth
`--with-token`	Read and trim the token from stdin; selects token auth
`--app-password`	Legacy flag name for API-token auth
`--client-id <clientId>`	Custom OAuth consumer key
`--client-secret <clientSecret>`	Custom OAuth consumer secret

BB_USERNAME supplies the email when -u is absent; BB_API_TOKEN supplies the token when -p or --with-token is absent. The mere presence of BB_API_TOKEN, even empty, selects token auth. See Environment variables.

Examples

bb auth login
printf '%s' "$BB_API_TOKEN" | bb auth login -u [email protected] --with-token
bb auth login --client-id YOUR_KEY --client-secret YOUR_SECRET
bb auth login --account personal   # add a second account

The flag retains its historical name, but Atlassian requires your account email for API tokens. Avoid literal secrets in arguments or shell history.

How it works

In a terminal, token login asks for any missing email or token. Prompts are disabled for pipes, redirected output, --json, --no-input, or BB_PROMPT_DISABLED. Empty stdin with --with-token fails with 5001; combining --with-token and -p fails with 5002.

OAuth opens a browser and waits for a callback at http://localhost:19872/callback. It only starts when stdin and stdout are terminals and neither --no-input nor BB_PROMPT_DISABLED is set; --json alone still allows it, with the “Opening browser” line on stderr. There is no device-code flow. Normal token expiry is refreshed automatically; revoked or invalid refresh credentials require another login.

API-token login stores the credentials, verifies them against GET /user, and clears them if verification fails. A failed login can replace and clear the current account’s previous credentials, so log in to a second account with --account <name>. After a successful login that account becomes the active one, and --json includes its name as account.

--app-password selects API-token auth; it does not restore support for Bitbucket app passwords.

Required scopes (API token)

Login and status need read:user:bitbucket. Include the scopes for your other commands as well. OAuth grants come from the consumer’s permissions; a custom consumer can grant more than the CLI’s requested scope list. See Token scopes.

`bb auth logout`

bb auth logout [options]

Examples

bb auth logout
bb auth logout --json

What gets removed

Logout clears the current account’s credentials for its authentication method. If that was the active account and others are saved, the first remaining one becomes active; JSON reports it as switchedTo. OAuth logout also removes custom consumer credentials. It attempts OAuth revocation first and preserves settings such as defaultWorkspace and aliases. If revocation fails, local credentials are still cleared and JSON includes revokeFailed: true.

`bb auth status`

bb auth status [options]

Examples

bb auth status
bb auth status --json

Output

✓ Logged in to Bitbucket
  Authentication: API Token
  Username: myuser
  Display name: My Name
  Account ID: 712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f
  Default workspace: myworkspace

The displayed username comes from Bitbucket, even when login used an email. OAuth adds a token-expiry line. The default workspace appears only when set. With more than one saved account, an Account: line names the one in use and an Other accounts: line lists the rest. JSON always includes account (the current account name) and accounts (all saved names). With no credentials, the command reports Not logged in, JSON is { "authenticated": false, "account": "default", "accounts": [] }, and it exits 1 (like gh auth status), so bb auth status >/dev/null && ... only continues when you are logged in. Invalid or expired credentials also exit 1. For a wider check of your setup, run bb doctor.

auth status --json and auth login --json both report method as "api_token" or "oauth". Earlier releases reported "basic" from auth status for API tokens. See JSON output.

`bb auth switch`

bb auth switch [account] [options]

Make a saved account the active one. Without a name, an interactive terminal asks which account to use; otherwise the command fails with 5001 and lists the saved accounts. An unknown name fails with 5002.

Examples

bb auth switch work
bb auth switch          # pick from a list
bb auth switch personal --json

JSON output is { "success": true, "account": "personal" }. To use another account for a single command without switching, pass --account <name> or set BB_ACCOUNT.

`bb auth token`

bb auth token [options]

Examples

bb auth token
bb auth token | pbcopy  # macOS clipboard
bb auth token --json

Output

Login method	Text output	JSON type
OAuth	Bearer access token, refreshed if needed	`bearer`
API token	Base64 of the stored email and token, separated by `:`	`basic`

For an existing OAuth login:

curl -H "Authorization: Bearer $(bb auth token)" https://api.bitbucket.org/2.0/user

For an API-token login:

curl -H "Authorization: Basic $(bb auth token)" https://api.bitbucket.org/2.0/user

This command deliberately reveals credentials. Base64 is reversible, not redaction. Keep its output out of logs, issue reports, and agent prompts.