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's default 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": ""
}

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 interact with multiple CAs, we recommend enabling contexts.

Contexts let you configure and select multiple CAs and configuration profiles. When 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 created when --context [name] is passed to any of the following:

When contexts are enabled, there's always a currently active context (step context current), and you can pass a --context name to any step ca, step ssh, or step-ca command to select a different 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 shows the current context's configuration path. To display the top-level configuration directory name ($STEPPATH) when contexts are enabled, use step path --base.

Here's how contexts are managed under the hood:

  • Context configuration files contexts.json and current-context.json are created in the top-level $STEPPATH.
  • Client configurations are stored in a profiles directory, and CA server configurations and data are stored in an authorities directory.
  • Two defaults.json files are created: One in the profiles tree, and one in the authorities tree. They are merged at runtime, and the defaults in profiles take precedence.

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.

Next Steps