Using the command line

Everything you do with Custodian, you do through the custodian command line. This page covers what is true of every command: the options they all accept, and the one shape an error always takes. Each command has its own page under this section.

Run a command with the noun and verb, then its options:

custodian records get rec_8VN2QJ4KpR --collection policies

Options every command accepts

These are set on the root command and apply to whichever command you run.

--timeout <seconds>

Bounds each request Custodian makes to the server. If a request runs past the bound, it is stopped and the command fails, rather than hanging.

The value is taken from, in order: the --timeout option, then the CUSTODIAN_TIMEOUT environment variable, then a built-in default of 30 seconds. So you can set a timeout for one command with the option, or for a session with the environment variable:

export CUSTODIAN_TIMEOUT=60

A value that is not a positive number of seconds is refused, naming where it came from:

error: --timeout must be a positive number of seconds (got "nope").

When a request does time out, the message names the operation and tells you what to change:

error: Cannot list devices: the request timed out after 30s. If the server is healthy but slow, raise the bound with --timeout <seconds> or the CUSTODIAN_TIMEOUT environment variable.

--yes

Answers yes to every confirmation a command would otherwise ask you. Use it to run a command that would normally stop for a prompt without anyone at the keyboard.

It does not skip a hard stop. In particular, custodian init still shows its recovery-code screen and still requires you to acknowledge it, even with --yes.

-v, --version

Prints the version and exits. For the version, the commit and the running program's own checksum, use custodian version.

--help

Prints usage for the command it follows — custodian --help, or custodian records --help, or custodian records get --help.

Colour

Output is coloured when it is written to a terminal. Set NO_COLOR to turn colour off, or FORCE_COLOR to keep it on when output is not a terminal.

Selecting a deployment and vault

Most commands act on one vault at one Custodian address. When you have signed in to only one, they use it. When you have signed in to more than one, name the one you mean with --url <api> and --vault <slug>; a command that cannot tell which you mean refuses and lists what is stored, rather than guessing. See signing in.

The shape of an error

When a command fails, it prints a single line to standard error, beginning with error: and naming the operation that failed and why:

error: Cannot read vault "acme": the API rejected your credentials (HTTP 401).

Custodian never prints a stack trace, and it never prints the raw body of a server response. If you see an error: line, the tool worked as intended and is telling you what went wrong — you did not break it. The line is enough to act on.