Signing in

Before you can run any command that reaches a vault, you sign in with an operator token. Signing in verifies the token against the vault and stores it in your machine's platform credential store, keyed by the Custodian address and the vault, so you can hold credentials for more than one vault at once.

Which store that is depends on your platform: on macOS the login keychain, on Linux the system secret service (libsecret). A macOS or Linux machine has a store; anything else does not — see Machines with neither store.

You get the operator token from whoever runs your Custodian server; it is the same kind of token custodian principal create prints.

custodian login

custodian login --url https://custodian.example.com --vault acme

Both --url and --vault are required. The token is not passed on the command line — an argument on the command line is readable by anyone who can list running processes. Give the token in one of three ways instead:

• pipe it on standard input: echo "$TOKEN" | custodian login --url … --vault …
• set the CUSTODIAN_TOKEN environment variable before running
• pass --token <token> (the least private of the three, and the option says so)

If you pass the token as a plain argument, Custodian refuses it:

error: A token must not be passed as a positional argument — an argument vector is readable from the process table. Use --token, pipe it on standard input, or set CUSTODIAN_TOKEN.

Custodian verifies the token before it stores anything. A token that does not authenticate, or that belongs to another vault, is refused and nothing is stored. On success it prints where you are signed in and what it did — and, importantly, that signing in creates no key material:

Signed in to vault "acme" (Acme Insurance) at https://custodian.example.com, region eu-west-1.
The credential is held in the system secret service (libsecret).
No key material was created — login only establishes who you are.
Next: run `custodian init` to give this vault its first device and key.

If the vault is already set up, the last line instead reads that there is nothing more to run.

Where the credential is held

The second line names the store for your platform. Custodian hands the token to that store's own tool on standard input — never on the command line, where an argument is readable by anyone who can list running processes.

On macOS, the token is held in the login keychain, and the second line reads:

The credential is held in the macOS login keychain.

On Linux, it is held in the system secret service (libsecret), as shown above. The whoami and logout output below names the same store for your platform.

Machines with neither store

A machine that is neither macOS nor Linux has no platform credential store. Custodian will not fall back to a file — a token written to your home directory is readable by anything running as you. It refuses and names the supported path:

error: No platform credential store is available on this machine. custodian holds a token in the macOS login keychain, or on Linux in the Secret Service (via secret-tool); this machine has neither. custodian will not fall back to a file, because a token written to your home directory is readable by anything running as you. Set the CUSTODIAN_TOKEN environment variable instead — that is the supported path everywhere else.

On such a machine, set CUSTODIAN_TOKEN and name the deployment with --url and --vault on each command.

When a stored secret cannot be read

Reading a credential back from the store can fail even when a matching entry is there — the store is locked, or the platform tool will not return the secret. When exactly one stored credential matches the deployment you named but its secret cannot be read, Custodian treats that entry as no credential at all and falls through to the CUSTODIAN_TOKEN environment variable, provided you also pass --url and --vault. A machine with a broken store entry but a valid token in the environment still runs.

Setting CUSTODIAN_TOKEN without naming the deployment is refused:

error: Using CUSTODIAN_TOKEN requires naming the deployment: pass --url <api> and --vault <slug>.

When no token resolves at all — the stored secret cannot be read and no CUSTODIAN_TOKEN stands in for it — the command refuses and names the store, rather than reporting that no stored credential matched:

error: A credential for acme @ https://custodian.example.com is stored, but its secret could not be read from the system secret service (libsecret).

This resolution is shared by custodian whoami and custodian init, so both accept the same env-token recovery and refuse the same way.

custodian whoami

Identifies the calling principal and its kind, shows which vault the credential reaches, and names where the credential is held.

custodian whoami --vault acme

Principal: operator (operator)
Vault:     acme (Acme Insurance)
Region:    eu-west-1
API:       https://custodian.example.com
Store:     the system secret service (libsecret)

The first line names the principal you are signed in as and its kind — operator, agent or service. Custodian reads the kind from the vault, not from your token.

custodian logout

Discards a stored credential. With one credential stored, you can omit the selectors; with more than one, name the one to discard with --url and --vault.

custodian logout --vault acme

Discarded the credential for vault "acme" at https://custodian.example.com from the system secret service (libsecret).

--all discards every stored credential:

custodian logout --all