Open Source

The `step` Command

Getting Help

step ships with extensive built-in help. To list available options and command groups, run step by itself. For help, use step help <command> or step help <command> <subcommand>.

Environment variables

STEPPATH The path where step stores configuration and state. This directory also holds step-ca state created with step ca init, including CA configuration, keys, certificates, and templates. Defaults to $HOME/.step.

STEPDEBUG When set to 1, step will provide extra diagnostic information for debugging. This variable can also be used with step-ca.

HTTPS_PROXY and NO_PROXY Configure proxies for outbound HTTPS traffic. See net/http.ProxyFromEnvironment documentation for details. Note that the system trust store is not trusted by step for the TLS handshake with the proxy server.

The proxy server will need to be configured to trust the CA.

Only HTTPS_PROXY is needed; step's outbound connections are all HTTPS.

Add a --root or STEP_ROOT These files contain both the step CA certificate, and the proxy CA certificate will be trusted by step.

Passing flags as environment variables

You can pass flags to step using environment variables, using STEP_<flag>. For example, STEP_RAW=true step ssh list is equivalent to step ssh list --raw. Command flags have precedence over environment variable flags, which in turn have precedence over the values in the configuration file.

Configuration file

The file $(step path)/config/defaults.json can contain a JSON object listing default values for any flags accepted by step commands. It is typically used to store CA connection information, eg:

{
  "ca-url": "https://ca.internal:8443",
  "fingerprint": "93cff06dc36251fb0c4985d0b5ed7265a368cd70697fba90355c93cc4aabff0d",
  "root": "/Users/carl/.step/certs/root_ca.crt",
  "redirect-url": ""
}

It is not currently possible to segment default keys in defaults.json by subcommand. All keys are applied to all step commands.

Contexts: Working with multiple CAs

By default, the step toolchain assumes a single CA is in use, and it will store client configuration, CA configuration, and state directories (config, certs, secrets, db, etc.) inside a single folder, $HOME/.step.

If you regularly work with multiple CAs, we recommend enabling contexts.

Contexts let you configure and select multiple CAs and configuration profiles. If this optional feature is enabled, the $HOME/.step folder will have a different layout.

Every context consists of a client configuration profile (including defaults.json), and a directory tree for CA configuration and state data (ca.json, CA roots, certificates, secrets, templates, db).

To enable contexts, pass the --context flag to any of the step setup commands, along with a label for your new context:

$ step ca bootstrap \
       --ca-url https://ca.internal:4443 \
       --fingerprint c8d3...7aa \
       --context vpn
The root certificate has been saved in /home/carl/.step/authorities/ca.internal/certs/root_ca.crt.
The authority configuration has been saved in /home/carl/.step/authorities/ca.internal/config/defaults.json.
The profile configuration has been saved in /home/carl/.step/profiles/ca.internal/config/defaults.json.
$ step context current
vpn
$ step path
/home/carl/.step/authorities/ca.internal

Contexts are enabled, and a new context is created, if --context [name] is passed to any of the following:

CA client bootstrap: step ca bootstrap

CA server init: step ca init

CA server startup: step-ca

SSH client bootstrap: step ssh config

When contexts are enabled:

Client configuration is stored in the profiles directory, and CA server configuration and data is stored in authorities directory.

Context configuration files contexts.json and current-context.json are created in the top-level $STEPPATH.

There is always a currently active context (step context current), but you can pass a --context name to any step ca, step ssh, or step-ca command to temporarily select a context for a single operation.

Use the step context command group to switch contexts, remove a context and its associated configuration, and view the current context.

The step path command will show the current context's path. To display the top-level configuration directory name ($STEPPATH) when contexts are enabled, use step path --base.

Two defaults.json files are created: One in the profiles tree, and one in the authorities tree. They are merged, and the one in profiles takes precedence.

Context configuration files contexts.json and current-context.json are created in the top-level $STEPPATH.

Migrating to Contexts

There is no support for automatically migrating a single-profile $STEPPATH configuration into its own context. Enabling contexts will preserve any previously existing configuration or state data in $STEPPATH, but it will not migrate your existing configuration tree into its own new context.

Extending `step`

The step command supports plugins for adding subcommands. A plugin is an executable file called step-COMMANDNAME-plugin located in $PATH or $STEPPATH/plugins. For example, a plugin named $STEPPATH/plugins/step-dns-plugin will execute when step dns is run. If you're writing a plugin, please follow our convention for CLI help by implementing eg. step dns help.