doctor and completion support the rest of the binary rather than doing anything to a blob: doctor reports on
the local setup — credentials, reachability, key scope, currency — and completion prints a shell completion
script. Neither takes a manifest, and completion needs no credentials at all.
blobhub doctor
Check credentials, permissions, API reachability, key scope, and CLI currency.
Reach for it when another command fails in a way its error code alone does not explain, or immediately after
installing on a new machine. It reports on the setup a command would have run under, without running one.
Synopsis
The three overrides are
whoami’s, so a key can be diagnosed before it is stored.
What it does
Seven checks run in a fixed order, each contributing exactly one row:✓ pass, ✗ fail, ! warn, - skip.
Under --json the payload carries checks — one entry per row, holding name, status (ok, fail, warn or
skip) and detail, the text the rendered row prints after the check’s name — and ok, which is false exactly
when some row is fail. Rows come in the order above, and the envelope’s schema_version sits alongside.
The report leaves a few things unsaid.
It never raises. Every check is wrapped, so a failure — an unreadable credentials file, a surprise from the
filesystem — becomes that check’s
fail row carrying its error code, and every later check still runs. A
diagnostic that dies on the first problem cannot report the second.
It runs with no credentials at all. Where every other command resolves a key or exits, doctor resolves the
URL and the key independently: a missing key is the credentials row’s failure and the key and scope rows’
skip, while api and version still run against the default URL. That state is precisely what the command
exists to report.
BLOBHUB_PROFILE
naming a profile that is not stored fails the credentials row even when BLOBHUB_API_KEY is set — which is the
honest report, since that combination exits 1 on every command that resolves credentials properly.
The version check talks to PyPI, not to BlobHub, with a two-second timeout, and deliberately does not carry
your API key to that third-party host. An unpublished package, a timeout or any network error all report latest unknown, and never fail the run.
Exit code
1 if any row is ✗, otherwise 0. A ! or - row never changes it.
doctor is the one command that can exit non-zero without printing an error: line, because its failure is a
report rather than an operation that failed.
Errors
doctor raises nothing — that is the point of it. These codes appear inside a row’s detail instead:
blobhub completion
Print a shell completion script for bash, zsh, or fish.
Synopsis
What it does
Writes a completion script to stdout, preceded by a comment naming the install one-liner for that shell. It needs no credentials and makes no network call. Append it to your shell’s startup file, or drop it where the shell looks for completions:--install flag: writing into a startup file is invasive, and >> already
does it in a way you can read first.
This is the one command exempt from --json. Its output is a shell script meant to be piped into a file, and
wrapping a script in a JSON envelope would make the only use of the command impossible — so it writes to stdout
directly. Passing --json changes nothing about what it prints.
Errors
None. The shell argument is a closed set, so an unsupported value is a usage error — exit2 — caught before the
script is generated:
See also
- Authentication — the credentials
doctorreports on. - Concepts — the platform behaviours behind several of the codes
doctorsurfaces. - Error codes — what each code in a
doctorrow means when a command raises it for real.