The `step` Command

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>.

• 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.

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.

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

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:

• CA client bootstrap: step ca bootstrap
• CA server init: step ca init
• SSH client bootstrap: step ssh config

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.

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.

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.

• Basic Crypto Operations