jwt-cli: Practical JWT Encoding and Decoding from the Shell

jwt-cli's Scope for Token Work

jwt-cli addresses a narrow but common developer task: creating a JSON Web Token from JSON data and decoding tokens that arrive through arguments or shell pipelines. Its intended users are developers working with authentication APIs, testing token flows, inspecting claims during debugging, or generating sample tokens for local tooling. The executable is named `jwt`, so a command such as `jwt help` addresses the installed binary rather than the Cargo package name.

The project supports arbitrary JSON claim bodies, some custom header values, and different secrets. That makes it more useful than a decoder limited to displaying a token received from somewhere else. It also supports prebuilt binaries for 64-bit Linux, macOS, and Windows. The README says Windows, macOS, and Linux are supported, while its installation section narrows the downloadable targets to 64-bit systems. Users on other targets are directed to build the project from source.

This is a token utility, not an HTTP authentication client. It does not fetch identity provider metadata, submit credentials to a login endpoint, or replace an API request. Those boundaries matter when choosing it for an onboarding flow or production authentication service.

How jwt-cli Handles JSON and Tokens

The encode command accepts JSON and a secret, then emits a JWT that a decode command can consume. The README demonstrates a direct pipeline in which the encoded output becomes the standard input for decoding. The `-` argument is therefore a stream boundary, not a special token value. This allows shell-native composition without storing an intermediate token in a file.

The dependency list provides a clearer view of the implementation. `clap` with its `derive` feature handles command-line parsing, while `serde` and `serde_json` provide Rust serialization support for JSON data. The `jsonwebtoken` dependency performs token encoding and decoding, and `chrono` supplies date and time types. `parse_duration` appears to support duration input, although the README does not document the exact expiration syntax or command flags.

For elliptic-curve keys, the README identifies a format constraint in the underlying `jsonwebtoken` library. SEC1 private keys are not supported directly for encoding or decoding and must first be converted to PKCS8. This is a concrete interoperability boundary. A key that another JWT library accepts cannot be assumed to work with jwt-cli until its format is known.

Installing jwt-cli on macOS, Linux, or Windows

Cargo is the most general installation method documented in the README because it is available across supported platforms after Rust and Cargo are installed. This command installs the package through Cargo and places the `jwt` binary in Cargo's bin directory, which is normally `~/.cargo/bin`. That directory must be present in `$PATH`.

cargo install jwt-cli

On macOS, Homebrew offers a prebuilt package path. Run the help command afterward to confirm that the executable is available to the shell.

brew install mike-engel/jwt-cli/jwt-cli
jwt help

Linux distributions have their own documented options. Arch Linux can install the package from the community repository with `pacman`.

pacman -S jwt-cli

On Windows, the README points to Scoop and describes jwt-cli as available in Scoop's main repository. The README does not show a Windows-specific shell-verification command, so `jwt help` is useful only if the installed terminal can resolve the executable.

scoop install jwt-cli

FreshPorts provides a FreeBSD route through `pkg`.

pkg install jwt-cli

Prebuilt release binaries are also linked from the repository's releases page. The README says unsupported targets require a source build. Contributors need `rustc` and `cargo` for that route.

A First jwt-cli Encode and Decode Pipeline

The shortest documented first use creates a token from a JSON object and immediately decodes it. The secret in this example is deliberately labeled `fake`; it is not a production credential. The encoded token remains in the shell pipeline, which makes this suitable for demonstrating the interface without writing a file.

jwt encode --secret=fake '{"hello":"world"}' | jwt decode -

The first process reads the JSON argument, encodes it with the supplied secret, and writes a token to standard output. The second process receives that token because its argument is `-`. What the reader sees depends on the installed command's output formatting, which is not reproduced in the README.

A second example places jwt-cli inside a longer authentication pipeline. `curl` requests an authentication API, `jq` extracts the `access_token` field, and `jwt decode -` inspects the resulting token.

curl <auth API> | jq -r .access_token | jwt decode -

The literal `<auth API>` is a placeholder from the README, not an endpoint supplied by the project. Users must replace it with their own URL. They should also account for the API's response format and local `jq` availability. The project does not wrap `curl`, so redirects, authentication headers, status handling, and response validation remain outside jwt-cli's scope.

Help, Completion, and Source Builds

Command-specific help is the correct place to discover encoding options such as header fields, algorithms, and expiration settings. The README does not reproduce the complete option list, so those details cannot be inferred safely from its examples.

jwt help
jwt help encode

Shell completion is generated for bash, elvish, fish, PowerShell, and zsh. For bash, the generated completion script is loaded with process substitution. The optional shell-profile guard first checks whether `jwt` can be found, then sources the generated output.

if hash jwt > /dev/null; then
  source <(jwt completion bash)
fi

Source contributors can run the repository's test command after installing `rustc` and `cargo`. This command invokes Cargo's test runner; it does not establish how comprehensive the test suite is.

cargo test

A contributor can then invoke the local executable through Cargo, either in the normal build profile or with release optimizations enabled.

cargo run -- help
cargo run --release -- help

The package uses Rust edition 2021 and defines its binary name as `jwt`. The repository also includes `Cargo.lock`, source files under `src/`, and tests under `tests/`, although the README does not explain the internal module design.

Limits, Alternatives, and Maintenance Signals

jwt-cli is the wrong tool when a workflow needs JWK retrieval, remote key-set refresh, issuer validation, audience checks, revocation handling, or an HTTP login exchange. The README describes encoding, decoding, custom headers, JSON claims, secrets, pipes, and local key-format handling. It does not document a complete token-validation policy engine.

A shell alternative using `jq` can extract and reshape JSON responses without becoming a dedicated JWT utility. It is a better fit when the data is ordinary JSON and no compact token serialization is required. For application code that must create or validate tokens inside a service, using a Rust JWT library through `jsonwebtoken` directly offers more control over integration and error handling, although it requires writing code rather than using a command.

Another limitation is key portability. SEC1 elliptic-curve private keys require conversion to PKCS8 because of the underlying library. This creates an operational step for workflows using that format. The README is also silent about rollback, automatic key discovery, token revocation, and a rollback path for upgrades.

The repository uses the MIT license, which permits reuse and modification under that license's terms. This is a licensing note, not legal advice. `Cargo.toml` identifies release `6.2.0`; the release list records it on 2024-11-27. The last push was on 2026-09-21, so the repository has recent repository activity, although that alone does not establish the compatibility of every dependency. Upgrade cost should be assessed against Cargo.lock, the changes in `jsonwebtoken`, and the key formats used in local scripts.

Editorial conclusion

Developers who frequently inspect or generate JWTs in shell scripts can adopt jwt-cli after checking their algorithm, key format, expiration, and secret-handling requirements. It is a poor fit for services that must validate remote tokens against a full policy set or users on unsupported 32-bit platforms. The first project-specific checks should be the command help for the required algorithm and the underlying jsonwebtoken documentation for supported key formats.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mike-engel/jwt-cli on GitHub
4. README
5. Releases