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": "" }

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:

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.

Next Steps