bb doctor¶
Check the configuration bb would load
bb doctor
Check the configuration bb would load, and report everything wrong with it at once.
A command stops at the first file it cannot use. bb doctor reads the stored, workspace and system files each on its own and reports, for each, where it is, whether it parses, every key the configuration schema rejects, with its line, and every valid key its file does not read: policy set in your own file mandates nothing.
It then shows where each effective setting comes from -- a flag, an environment variable, a .env file, a configuration file, the Windows registry or the built-in default -- and what it overrides, and checks that the OS keyring answers when keyring-backed storage is required.
It also shows where shell completion is set up for each shell installed, and where the agent skill is installed, in .agents/skills or .claude/skills, and whether each copy is the one bb ai skill install writes now. A copy of a skill this bb no longer carries is reported with the directory to delete.
It needs no configured host, never contacts Bitbucket, and never prints a secret: a token or password is reported as configured, with where it is held.
Exit status is 0 only when there is nothing to fix, and 1 for any issue the report shows. Under --json a run with issues writes the failure envelope instead: its message summarises the issues, and error.details names each one under its own key: file/<file>, violation/<file>/<key path>, ignored/<file>/<key>, setting/<name>, keyring, completion/<shell>/<scope>, completion/powershell/<edition> or skill/<skill>/<scope>/<location>, with the key path written as a JSON Pointer.
# Check every configuration file bb would load, and where each setting comes from
bb doctor
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
files list of object or null The stored, workspace and system
configuration files, in that order.
tier stored|workspace|system Which configuration file this is.
path? string Where the file is.
pathFrom string What chose the path: the variable that
set it, default, search for a workspace
file found above the working directory,
or machine for the fixed system
location.
read boolean Whether bb reads this file at all.
notRead? string Why bb does not read it, when it does
not.
exists boolean Whether the file is there.
secrets list of object or null Hosts with a plaintext credential in
this file's insecure_secrets.
host string The host the credential is for.
token boolean Whether a plaintext token is held.
password boolean Whether a plaintext password is held.
settings list of object or null Every effective setting and where it
came from.
name string The setting, named as its configuration
key where it has one.
value? string The effective value.
secret boolean Whether this is a token or password,
whose value is never reported.
configured boolean Whether anything sets it.
source object Where the effective value came from.
kind flag|environment|dotenv|override|workspace|stored|system|registry|keyring|default What kind of place: a flag, the
environment, a .env file, a value passed
by the program running bb, one of the
three configuration files, the Windows
registry, the OS keyring, or the
built-in default.
name? string The flag, variable, key, keyring entry
or registry value.
path? string The file, .env file or registry key it
was found in.
shadowed list of object or null Other places that set it and lost to
source.
kind flag|environment|dotenv|override|workspace|stored|system|registry|keyring|default What kind of place: a flag, the
environment, a .env file, a value passed
by the program running bb, one of the
three configuration files, the Windows
registry, the OS keyring, or the
built-in default.
name? string The flag, variable, key, keyring entry
or registry value.
path? string The file, .env file or registry key it
was found in.
keyring object The OS keyring, checked only when
keyring-backed storage is required.
required boolean Whether keyring-backed storage is
required.
requiredBy? object What requires it.
kind flag|environment|dotenv|override|workspace|stored|system|registry|keyring|default What kind of place: a flag, the
environment, a .env file, a value passed
by the program running bb, one of the
three configuration files, the Windows
registry, the OS keyring, or the
built-in default.
name? string The flag, variable, key, keyring entry
or registry value.
path? string The file, .env file or registry key it
was found in.
checked boolean Whether the keyring was probed.
reachable boolean Whether the probe reached it.
completion list of object or null Shell completion for each shell
installed, and for any other shell
something of bb's was found for.
shell bash|zsh|fish|powershell The shell.
installed boolean Whether the shell is on PATH.
places list of object or null Every place completion is set up for
this shell.
kind setup|script|package|startup setup for what bb completion install
writes, script for a script saved from
bb completion <shell>, package for the
script a package manager installed,
startup for a startup file somebody
added bb completion to by hand.
scope user|all-users Whose shells read it: user for the
person running bb, all-users for
everyone on the machine.
edition? PowerShell 7|Windows PowerShell 5.1 Which PowerShell reads it.
path string The file.
current boolean Whether it is exactly what this bb
writes: bb completion install's loader
as it is now, or the script bb
completion <shell> prints.
skills list of object or null Each agent skill bb carries, in every
place an agent reads it from:
.agents/skills and .claude/skills, under
the working directory and under the home
directory.
skill bb The skill.
scope project|global project for the working directory and
the directories above it up to its
repository's root, global for the home
directory, which bb ai skill install
writes to with --global.
location agents|claude agents for .agents/skills, which most
agents read; claude for .claude/skills,
which Claude Code reads.
path string The skill's file in this place, whether
or not it is there.
state not_installed|current|repository not_installed; current for exactly what
bb ai skill install writes now;
repository for the repository's copy,
which npx skills add installs.