Step CLI: a command-line toolkit for X.509, JOSE and OAuth work

What Step CLI actually solves

Most teams end up with certificate work spread across openssl invocations, a browser, a cloud console and a shell script nobody wants to own. Step CLI collapses that into one binary with grouped subcommands: step certificate for X.509, step crypto for JOSE and related primitives, step oauth for token acquisition, step ssh for SSH certificates, and step ca for talking to a CA.

The README frames the tool two ways at once. It is a standalone crypto utility, and it is also "a client for the step-ca online Certificate Authority (CA) server". That dual role matters when you evaluate it. The certificate, crypto and oauth groups work without any server. The ca and ssh groups assume one.

The audience is therefore narrower than the feature list suggests. Platform and infrastructure engineers who already operate a private CA get the most from it. Developers who need a self-signed certificate for a local service get a useful subset. Someone looking for a secrets manager is in the wrong repository.

How the command tree and CA client fit together

The repository is a Go module, github.com/smallstep/cli, built with urfave/cli for command dispatch. The top-level layout separates concerns cleanly: cmd/ holds the entry point, command/ holds the subcommand implementations, flags/ holds flag definitions, and pkg/ and internal/ hold supporting code. Autocomplete scripts for shells live in autocomplete/, with powershell/ and debian/ packaging alongside them.

The dependency list in go.mod shows where the real work happens. github.com/smallstep/certificates is the client library for step-ca, go.step.sm/crypto supplies the underlying crypto helpers, github.com/go-jose/go-jose/v3 handles JOSE, github.com/pquerna/otp handles one-time passwords, and github.com/smallstep/truststore writes certificates into the system trust store. Linting of certificates comes from github.com/smallstep/zlint and github.com/smallstep/zcrypto.

The data flow for the CA path is: step reads or creates a key pair locally, builds a CSR, sends it to step-ca, and writes the returned certificate plus the root bundle to disk. For the standalone path there is no network hop at all; step manipulates files and prints results. Knowing which path a subcommand takes tells you whether it will work offline.

Installing Step CLI and running a first inspection

The README points to the installation page at smallstep.com/docs/step-cli/installation for packaged installs. If you prefer to build from source, the Makefile documents the flow: run make bootstrap once to set up the local environment, then make build. The binary name defaults to step and the build output path defaults to bin, both overridable through the BINNAME and PREFIX variables.

make bootstrap
make build
./bin/step version

After the build you should have a step executable under bin/. Running step version prints the version string that the build embedded through the linker flags.

Once you have the binary, the quickest useful thing to do is inspect a certificate that already exists on the machine. The certificate group covers this without contacting any server.

step certificate inspect https://smallstep.com

That command fetches the certificate presented by the host and prints its contents. The README lists inspect as working on certificates "on disk or in use by a remote server", so the same subcommand accepts a file path when you want to examine a local PEM instead. From there, step certificate lint checks a certificate against RFC 5280 and the CA/Browser Forum baseline requirements, which is the step worth running before you ship an internal CA anywhere near production.

Where Step CLI stops being the right tool

The SSH commands are the clearest boundary. The README states plainly that step ssh requires "an online or offline step-ca instance". There is no mode where step ssh issues certificates on its own. If your team has no step-ca and no plan to run one, that entire command group is unavailable to you.

The ACME support has a similar edge. Step CLI can act as a client for "any ACMEv2 compliant CA server", but the README says that with an ACME CA, step supports the http-01 challenge type. It does not claim DNS-01 or TLS-ALPN-01. If your issuance path depends on DNS validation because the host is not reachable on port 80, that constraint decides the architecture before you write any code.

There is also a plain scope limit. The README describes a toolkit for PKI and crypto operations. It does not describe storage of secrets, rotation policy engines, or dynamic credentials. Teams that reach for Step CLI expecting Vault-shaped behaviour will find the certificate half and not the secrets half.

Step CLI against HashiCorp Vault for certificate work

Vault is the obvious comparison because the search data around this project keeps pairing the two. The difference is architectural rather than a matter of feature counts.

Vault runs as a server with a storage backend, an auth method system and a secrets engine model. Its PKI secrets engine issues certificates from inside that server, and clients talk to it over an HTTP API. The certificate authority, its state and its policy all live in the Vault deployment.

Step CLI is a client binary. The state lives in step-ca, a separate project that the README links to, and step is the tool you point at it. That separation means you can use step certificate and step crypto with no server at all, which Vault does not offer, and it means the CA is a distinct thing you deploy and back up rather than a mount inside a larger system. If you already run Vault for secrets and only need occasional certificate inspection, adding step as a local utility is a smaller change than standing up step-ca. If you want certificate issuance governed by the same policy engine as your other secrets, the Vault model is the one that already does that.

Maintenance cadence, build requirements and licensing

The repository is not archived, and the last push was on 2026-09-22. Release activity is visible in the tags: v0.30.6 on 2026-06-10, v0.30.7-rc1 on 2026-06-11, and v0.30.7-rc2 on 2026-09-22. Note the gap between the 0.30.6 stable release and the second release candidate; if you pin to stable, you are tracking a line that has been sitting on a release candidate for a while.

Upgrade cost is mostly a Go toolchain question. go.mod declares go 1.26.0, so building from source requires a toolchain at least that new. The Makefile defaults to CGO_ENABLED=0 unless you override it with CGO_OVERRIDE, which keeps cross-compilation straightforward but means anything depending on cgo is off by default. Packaged installs through the documented installation page sidestep the toolchain requirement entirely.

On licensing: the repository is Apache-2.0, and the README links to the Apache 2.0 text. The README also carries a CLA assistant badge, which indicates contributions go through a contributor licence agreement. Apache-2.0 is permissive and includes a patent grant, but it is worth reading the NOTICE and attribution expectations in the LICENSE file in the repository rather than assuming, and this is not legal advice.

Editorial conclusion

Adopt Step CLI if you run step-ca or another ACMEv2 CA and want certificate issuance, renewal and inspection from a script rather than a browser. Do not adopt it expecting a general-purpose secrets store: it has no secret engine, and the SSH commands need a running step-ca instance. Before you commit, verify that step ca bootstrap works against your CA and that your Go toolchain satisfies the go 1.26.0 directive in go.mod, because those two things decide whether the workflow you are planning is actually available.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. smallstep/cli on GitHub