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.

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.

Machines with no credential store

On a machine with 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 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 on a headless machine.

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

custodian whoami

Shows which vault the stored credential reaches, and where the credential is held.

custodian whoami --vault acme

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

If the vault is not yet set up, the Keys: line tells you to run custodian init.

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