bb auth¶
Log in, check the setup, and manage tokens, keys and git credentials
22 commands.
bb auth alias- Add, list and remove the other host names a stored server answers to (4 commands)
bb auth git-credential- Git credential helper (invoked by git, not run directly)
bb auth gpg-key- Add, list and remove your GPG keys (4 commands)
bb auth identity- Show authenticated user identity
bb auth login- Store credentials for a Bitbucket host
bb auth logout- Remove stored credentials for a Bitbucket host
bb auth server- List the stored servers, and choose the default one (2 commands)
bb auth setup-git- Configure git to authenticate to Bitbucket through bb
bb auth status- Show the configured target and verify it works
bb auth token- Create, list, update and revoke HTTP access tokens (5 commands)
bb auth token-url- Show personal access token creation URL
bb auth alias¶
Add, list and remove the other host names a stored server answers to
add- Add aliases to a stored server context
discover- Discover aliases from the first accessible repository clone links
list- List aliases for a stored server context
remove- Remove an alias from a stored server context
bb auth alias add¶
Add aliases to a stored server context
bb auth alias add <alias> [alias...] [flags]
# Teach bb that the SSH clone host belongs to this Bitbucket
bb auth alias add git.example.com:7999 --host https://bitbucket.example.com
--host string- Bitbucket host URL
Also takes the global flags.
Dry run: Shows that it would add host aliases, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
host string Server context the aliases belong to.
aliases list of string or null Aliases now stored for that context.
bb auth alias discover¶
Discover aliases from the first accessible repository clone links
bb auth alias discover [flags]
Discovered aliases are added to the ones already stored. Aliases added by hand are kept, because discovery cannot find every alias -- an instance whose SSH clone host differs from its web URL is the documented case for adding one manually, and it would be undone by every later discovery run.
Pass --replace to store only what was discovered. Anything dropped is named in the output.
# Add the aliases found in a repository's clone links
bb auth alias discover --host https://bitbucket.example.com
# Store only what was discovered, dropping any added by hand
bb auth alias discover --host https://bitbucket.example.com --replace
--host string- Bitbucket host URL
--replace- Store only the discovered aliases, dropping any others
Also takes the global flags.
Dry run: Shows that it would replace host aliases, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
host string Server context that was probed.
aliases list of string or null Aliases now stored, which is the discovered set merged with what was already there
unless --replace was passed.
discovered list of string or null What this run found.
removed list of string or null Aliases that were stored before and are not any more, which only --replace can
produce.
bb auth alias list¶
List aliases for a stored server context
bb auth alias list [flags]
# The aliases stored for a host
bb auth alias list --host https://bitbucket.example.com
--host string- Bitbucket host URL
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data
host string Server context the aliases belong to.
aliases list of string or null Aliases now stored for that context.
bb auth alias remove¶
Remove an alias from a stored server context
bb auth alias remove <alias> [flags]
# Remove one alias
bb auth alias remove git.example.com:7999 --host https://bitbucket.example.com
--host string- Bitbucket host URL
-y, --yes- Confirm without being asked
Also takes the global flags.
Dry run: Shows that it would remove a host alias, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
host string Server context the aliases belong to.
aliases list of string or null Aliases now stored for that context.
bb auth git-credential¶
Git credential helper (invoked by git, not run directly)
bb auth git-credential <get|store|erase> [flags]
Supply stored Bitbucket credentials to git on demand.
git invokes this; you do not normally run it yourself. Configure it with:
bb auth setup-git
Credentials are read from the same place bb auth login stores them, so git and bb stay in agreement and no token is ever written into a repository.
# What git runs to ask for a credential; run it yourself to debug a failed push
printf 'protocol=https\nhost=bitbucket.example.com\n\n' | bb auth git-credential get
--config string- Configuration file holding the login to answer with, in place of BB_CONFIG_PATH
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json: this command writes no document of its own: speaks git's credential helper protocol on stdout, which git parses and nothing else reads
bb auth gpg-key¶
Add, list and remove your GPG keys
add- Add a personal GPG key
clear- Clear all personal GPG keys
list- List personal GPG keys
remove- Remove a personal GPG key
bb auth gpg-key add¶
Add a personal GPG key
bb auth gpg-key add <key-file-or-text>
# Add the public key in a file
bb auth gpg-key add public-key.asc
Also takes the global flags.
Dry run: Shows the change it would make, without making it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data list of object
id? string Key identifier, which bb auth gpg-key remove also accepts.
emailAddress? string Email address the key is bound to.
fingerprint? string Fingerprint, which bb auth gpg-key remove also accepts.
expiryDate? integer When the key expires, in milliseconds since the epoch.
text? string The public key itself.
subKeys? list of object Subkeys, when the key has any.
expiryDate? integer When the subkey expires, in milliseconds since the epoch.
fingerprint? string Fingerprint of the subkey.
bb auth gpg-key clear¶
Clear all personal GPG keys
bb auth gpg-key clear [flags]
# Remove every GPG key of yours
bb auth gpg-key clear
-y, --yes- Confirm clearing of all GPG keys
Also takes the global flags.
Dry run: Shows the change it would make, without making it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status string Outcome of the command.
bb auth gpg-key list¶
List personal GPG keys
bb auth gpg-key list [flags]
# Your GPG keys, with the id and fingerprint of each
bb auth gpg-key list
--all- Return every result rather than the first --limit
--limit int- Maximum number of results to return (default 25)
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data list of object
id? string Key identifier, which bb auth gpg-key remove also accepts.
emailAddress? string Email address the key is bound to.
fingerprint? string Fingerprint, which bb auth gpg-key remove also accepts.
expiryDate? integer When the key expires, in milliseconds since the epoch.
text? string The public key itself.
subKeys? list of object Subkeys, when the key has any.
expiryDate? integer When the subkey expires, in milliseconds since the epoch.
fingerprint? string Fingerprint of the subkey.
bb auth gpg-key remove¶
Remove a personal GPG key
bb auth gpg-key remove <id-or-fingerprint> [flags]
# By the id or fingerprint bb auth gpg-key list prints
bb auth gpg-key remove 3AA5C34371567BD2
-y, --yes- Confirm without being asked
Also takes the global flags.
Dry run: Shows the change it would make, without making it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status string Outcome of the command.
removed string The id or fingerprint that was removed, as it was given on the command line.
bb auth identity¶
Show authenticated user identity
Aliases: bb auth whoami
bb auth identity [flags]
# Who the stored credential authenticates as
bb auth identity
# On a host other than the default
bb auth identity --host https://bitbucket.example.com
--host string- Bitbucket host URL (defaults to the configured host)
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data
bitbucketUrl string Base URL the identity lookup went to.
user object
id? integer User identifier.
name? string Username.
displayName? string Human-readable name.
emailAddress? string Email address, when the instance exposes it.
slug? string URL-safe form of the username.
type? string Account kind: NORMAL for a person, SERVICE for an integration account.
active boolean Whether the account is enabled.
bb auth login¶
Store credentials for a Bitbucket host
bb auth login <host> [flags]
Prefer the stdin forms. A secret passed as a flag value appears in the process argument list, where any local user can read it through ps or /proc, and where the shell records it in history:
printf '%s' "$BITBUCKET_TOKEN" | bb auth login https://bitbucket.example.com --token-stdin
Credentials are stored in the OS keyring. Where no keyring is available — headless servers, most containers, WSL without gnome-keyring — the login fails rather than write the secret to disk unencrypted. Pass --allow-insecure-storage to keep it in the config file in plaintext instead, or set BITBUCKET_TOKEN in the environment and skip the login. BB_REQUIRE_KEYRING=1 and the require_keyring policy refuse plaintext even with --allow-insecure-storage.
# Store a personal access token, read from stdin
printf '%s' "$BITBUCKET_TOKEN" | bb auth login https://bitbucket.example.com --token-stdin
# A username and password instead of a token
printf '%s' "$BITBUCKET_PASSWORD" | bb auth login https://bitbucket.example.com \
--username alice --password-stdin
# A second host, leaving the default where it is
printf '%s' "$STAGING_TOKEN" | bb auth login https://bitbucket-staging.example.com \
--token-stdin --set-default=false
# On a host with no keyring, keep the credential in the config file in plaintext
printf '%s' "$BITBUCKET_TOKEN" | bb auth login https://bitbucket.example.com \
--token-stdin --allow-insecure-storage
--allow-insecure-storage- Where the OS keyring is unavailable, store the credential in the config file in plaintext instead of failing
--client-cert string- Path to PEM client certificate for mTLS
--client-key string- Path to PEM client key for mTLS
--discover-aliases- Discover host aliases from the first accessible repository clone links (default true)
--password-stdin- Read the basic-auth password from stdin
--require-keyring- Fail if the OS keyring is unavailable instead of storing credentials in plaintext
--set-default- Set host as default target (default true)
--token-stdin- Read the access token from stdin
--username string- Username for basic auth
Also takes the global flags.
Dry run: Shows that it would store credentials, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
host string Host the credentials were stored for.
aliases list of string or null Aliases stored for this server context.
authMode token|basic Stored authentication mode: token or basic.
usedInsecureStorage boolean True when the system keyring was unavailable and the credential went to
the config file instead.
bb auth logout¶
Remove stored credentials for a Bitbucket host
bb auth logout [flags]
# Remove the credentials of the default host
bb auth logout
# Of a named host
bb auth logout --host https://bitbucket.example.com
--host string- Bitbucket host URL (defaults to the configured host)
Also takes the global flags.
Dry run: Shows that it would remove stored credentials, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status string Outcome of the command.
bb auth server¶
List the stored servers, and choose the default one
bb auth server list¶
List stored server contexts
bb auth server list
# Every host bb holds credentials for
bb auth server list
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data
servers list of object or null Stored server contexts.
host string Bitbucket base URL.
aliases list of string or null Alternate hostnames that resolve to this context, for example an SSH clone host.
authMode token|basic|none How bb authenticates to this host: token, basic, or none.
username? string Stored username, present for basic auth.
isDefault boolean Whether this is the context bb uses when no host is named.
bb auth server use¶
Set the active default server context
bb auth server use [host] [flags]
# Make a stored host the default
bb auth server use https://bitbucket.example.com
--host string- Bitbucket host URL
Also takes the global flags.
Dry run: Shows that it would change the default host, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status string Outcome of the command.
defaultHost string Host bb will now use when no other is named.
bb auth setup-git¶
Configure git to authenticate to Bitbucket through bb
bb auth setup-git [flags]
Configure git to ask bb for Bitbucket credentials.
This replaces the need to embed credentials in a repository or in a remote URL. The configuration is scoped to the Bitbucket host, so git never offers these credentials to any other remote.
# Let git push and pull authenticate through bb, in every repository
bb auth setup-git
# In the current repository only
bb auth setup-git --global=false
# Take over from a credential helper git already has for the host
bb auth setup-git --force
--force- Overwrite an existing credential helper for this host
--global- Write to global git config rather than the current repository (default true)
--host string- Bitbucket host URL (defaults to the configured host)
Also takes the global flags.
Dry run: Shows that it would configure git to authenticate through bb, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
host string Scheme and host the helper was configured for.
key string Git config key that was written.
helper string Value written to that key.
scope global|local Which git config the entry went into: global or local.
bb auth status¶
Show the configured target and verify it works
bb auth status [flags]
Reports the resolved host, how the credential is stored, whether that credential still authenticates, and whether git is set up to authenticate through bb.
Each line says whether that part works, so an expired token, an unreachable host and a working setup read differently, and what to do when it does not.
Lines marked ! are advisory: they report something worth knowing that does not mean the setup is broken. The git credential helper is one — it is needed to git push and irrelevant to anything that only calls the API — so it is reported but never fails the command.
By default the exit status does not depend on the checks. Pass --check to exit non-zero when a non-advisory check fails, which is the form worth putting in CI.
Under --json the exit status is always zero and the verdict is the "ok" field. Machine output is a single document on stdout, so a failing exit would replace the findings with an error envelope — losing exactly the detail that was asked for.
# Show the host, how the credential is stored and whether it still works
bb auth status
# In CI: exit non-zero when a check fails
bb auth status --check
--check- Exit non-zero when a check fails (for CI)
--host string- Bitbucket host URL (defaults to the configured host)
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data
ok boolean Whether every non-advisory check passed.
bitbucketUrl string The configured Bitbucket base URL.
bitbucketVersionTarget string The version BITBUCKET_VERSION_TARGET records, empty when it is not
set. bb does not act on it.
authMode token|basic|none How bb authenticates: token, basic, or none.
authSource string Where that credential came from: stored (a configuration file or the
keyring), env (BITBUCKET_TOKEN or the basic-auth variables), or
env/default when neither supplied one.
credentialStorage string How the credential is held.
checks list of object or null What was verified, in the order it was checked.
name string What was checked.
ok boolean Whether the check passed.
advisory boolean Whether failing this check means the setup is broken.
detail? string The finding: who you are, or what went wrong.
remedy? string What to do about it.
bb auth token¶
Create, list, update and revoke HTTP access tokens
create- Create an HTTP access token
get- Get an HTTP access token by ID
list- List HTTP access tokens
revoke- Revoke an HTTP access token by ID
update- Update an HTTP access token name or permissions
bb auth token create¶
Create an HTTP access token
bb auth token create [name] [flags]
# A token of your own that expires in 90 days
bb auth token create "CI token" --permission REPO_READ --expiry-days 90
# A token for one project
bb auth token create "Release bot" --project PROJ --permission PROJECT_WRITE
# A token for one repository
bb auth token create "Deploy" --repo PROJ/repo --permission REPO_READ
--expiry-days int- Number of days before the token expires (0 for never)
--name string- Name of the access token
--permission strings- Permissions to grant (repeat flag or separate with commas)
Inherited from bb auth token:
--project string- Project key for project access token scope
--repo string- Repository reference (projectKey/repositorySlug) for repository access token scope
--user string- User slug for personal access token scope
Also takes the global flags.
Dry run: Shows the change it would make, without making it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
id? string Token identifier, for bb auth token get, update and revoke.
name? string Token name.
createdDate? integer When the token was created, in milliseconds since the epoch.
token string The token secret.
bb auth token get¶
Get an HTTP access token by ID
bb auth token get <token-id>
# One of your own tokens, by the id bb auth token list prints
bb auth token get 1827364510
# A repository's token
bb auth token get 1827364510 --repo PROJ/repo
Inherited from bb auth token:
--project string- Project key for project access token scope
--repo string- Repository reference (projectKey/repositorySlug) for repository access token scope
--user string- User slug for personal access token scope
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data
id? string Token identifier, for bb auth token get, update and revoke.
name? string Token name.
createdDate? integer When the token was created, in milliseconds since the epoch.
bb auth token list¶
List HTTP access tokens
bb auth token list [flags]
# Your own tokens
bb auth token list
# The tokens of a project, of a repository, or of another user
bb auth token list --project PROJ
bb auth token list --repo PROJ/repo
bb auth token list --user alice
--all- Return every result rather than the first --limit
--limit int- Maximum number of results to return (default 25)
Inherited from bb auth token:
--project string- Project key for project access token scope
--repo string- Repository reference (projectKey/repositorySlug) for repository access token scope
--user string- User slug for personal access token scope
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data list of object
id? string Token identifier, for bb auth token get, update and revoke.
name? string Token name.
createdDate? integer When the token was created, in milliseconds since the epoch.
bb auth token revoke¶
Revoke an HTTP access token by ID
bb auth token revoke <token-id> [flags]
# Revoke one of your own tokens
bb auth token revoke 1827364510
-y, --yes- Confirm without being asked
Inherited from bb auth token:
--project string- Project key for project access token scope
--repo string- Repository reference (projectKey/repositorySlug) for repository access token scope
--user string- User slug for personal access token scope
Also takes the global flags.
Dry run: Shows the change it would make, without making it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status string Outcome of the command.
bb auth token update¶
Update an HTTP access token name or permissions
bb auth token update <token-id> [flags]
# Rename a token
bb auth token update 1827364510 --name "CI token (read-only)"
# Replace the permissions of a project's token
bb auth token update 1827364510 --project PROJ --permission PROJECT_READ
--name string- New name for the access token
--permission strings- New permissions to set (repeat flag or separate with commas)
Inherited from bb auth token:
--project string- Project key for project access token scope
--repo string- Repository reference (projectKey/repositorySlug) for repository access token scope
--user string- User slug for personal access token scope
Also takes the global flags.
Dry run: Shows the change it would make, without making it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
id? string Token identifier, for bb auth token get, update and revoke.
name? string Token name.
createdDate? integer When the token was created, in milliseconds since the epoch.
bb auth token-url¶
Show personal access token creation URL
bb auth token-url [flags]
# Where to create a personal access token on a host
bb auth token-url --host https://bitbucket.example.com
--host string- Bitbucket host URL (defaults to the configured host)
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data
bitbucketUrl string Base URL the token page belongs to.
tokenUrl string Page to create a personal access token on.