login stores a credential, whoami reports the identity a command would
run as right now, logout removes one, and profile ls / profile use list and switch between the credentials
you have stored.
A credential is a profile — an API key plus the API URL it belongs to — kept in
~/.blobhub/credentials.yaml, written atomically at mode 0600 and refused on load if any group or other
permission bit is set. The CLI never repairs the mode for you, and it never prints a key: not in command output,
not in an error message, not in the --json payload.
In CI you need none of these commands. BLOBHUB_API_KEY resolves on its own, with no credentials file present at
all and with no warning — see Configuration for the full precedence ladder.
blobhub login
Authenticate interactively and store the result as a named profile.
Synopsis
What it does
- Prompts for the API URL, offering
--api-url’s value; press Enter to take it. - Prompts for the API key without echoing it, so the key never appears on screen or in your shell history.
- Fails with
AUTH_INVALIDon an empty key, before any network call. - Validates the key against
GET /v1/users/me. A rejection there is alsoAUTH_INVALID. - Writes the profile into
~/.blobhub/credentials.yamlat0600and prints the identity it resolved:
--json the payload carries profile, url, and user — the record GET /v1/users/me returned — plus
the envelope’s schema_version. The key is not among them, here or anywhere else.
The first profile you store becomes the default. Later logins add or replace a profile but leave the default
where it is; move it with blobhub profile use.
Unlike blobhub-worker, login has no identity-change guard. Logging in again — under the same profile name
or a new one — simply replaces or adds a profile, whoever the new key belongs to. A CLI switches identities by
design; a worker bound to one identity for the life of a process does not.
Errors
That last row is worth reading twice:
CREDENTIALS_NOT_FOUND covers a file that is present but unusable, not only
one that is absent.
blobhub logout
Remove a stored profile, or every profile with --all.
Synopsis
What it does
Removes the named profile — or the default one, when you name none — and rewrites the credentials file. With--all, every profile goes and the default is cleared. One line is printed per profile removed:
--json the payload carries removed, the list of profile names that went — empty when there was nothing
to remove.
Removing the default profile leaves the installation with no default at all, and nothing chooses a new one:
a later login sets the default only when no other profile exists. Until you run blobhub profile use, every
command must name its profile with --profile or BLOBHUB_PROFILE, or supply a key some other way.
Errors
logout --all against no credentials file at all is not an error: nothing is removed, nothing is printed, and the
exit code is 0.
blobhub whoami
Show the resolved identity, profile, and key scope.
Synopsis
What it does
Resolves a key and a URL exactly as every other command does, callsGET /v1/users/me with them, then probes
GET /v1/users/me/orgs to characterise the key’s scope, and prints four lines:
--json the payload carries profile (null when no profile was involved), url, user and scope,
plus the envelope’s schema_version.
This is the command to run when you are unsure which credential a command will pick up. Profile: (none) means
no profile was involved at all — the key came from --api-key or BLOBHUB_API_KEY.
The scope line
A
restricted key is a valid key. By the time the probe runs, GET /v1/users/me has already accepted it —
the probe is enrichment, not authentication. restricted is the expected reading for exactly the org- and
blob-scoped keys the platform recommends for automation, and such a key drives every command here except the
admin-scoped reads.
unknown says nothing about the key either. It means the probe itself failed — a network error, or a server
error on that one route — so the CLI reports what it observed rather than guessing full.
Errors
blobhub profile ls
List stored profiles, marking the default.
Synopsis
What it does
Reads the credentials file — no network call — and prints one line per profile in name order, with* against
the default:
--json the payload carries profiles — one entry per profile holding name, url and a boolean
default — and default, the default profile’s name or null. No key appears in either.
No profiles, or no credentials file at all, prints nothing and exits 0.
Errors
blobhub profile use
Set the default profile.
Synopsis
What it does
Points the credentials file’sdefault at an already-stored profile, and prints:
--json the payload carries default, the profile name now set as the default.
It stores nothing new: the profile must exist. This is how you recover a default after logout removed it, and
how you switch between environments without re-entering a key.
Errors
See also
- Concepts — what is shared across the binary and what belongs to a blob domain.
- Configuration — the credentials file these commands write, and the precedence ladder above it.
- Create API Key — where an org- or blob-scoped key comes from.
- Utilities —
doctordiagnoses a credential these commands cannot explain. - Error codes —
AUTH_INVALID,PROFILE_NOT_FOUNDand every other code above, with its remediation.