1# jwt-cli 2 3[](https://dependabot.com) 4 5A super fast CLI tool to decode and encode JWTs built in [Rust](https://rust-lang.org). 6 7 8[]() 9 10`jwt-cli` is a command line tool to help you work with JSON Web Tokens (JWTs). Like most JWT command line tools out there, you can decode almost any JWT header and claims body. Unlike any that I've found, however, `jwt-cli` allows you to encode a new JWT with nearly any piece of data you can think of. Custom header values (some), custom claim bodies (as long as it's JSON, it's game), and using any secret you need. 11 12On top of all that, it's written in Rust so it's fast and portable (windows, macOS, and linux supported right now). 13 14# Installation 15 16Install `jwt-cli` via [Homebrew](https://brew.sh) (macOS), [Cargo](https://www.rust-lang.org/tools/install) (cross-platform), and [FreshPorts](https://www.freshports.org/www/jwt-cli) (FreeBSD). If you intend to use one of these methods, [skip ahead](#homebrew). 17 18You may also install the binary from the [release](https://github.com/mike-engel/jwt-cli/releases) page, if you're unable to use Homebrew or Cargo install methods below. 19 20Only 64bit linux, macOS, and Windows targets are pre-built. Sorry if you're not on one of those! You'll need to build it from the source. See the [contributing](#contributing) section on how to install and build the project. 21 22You should install it somewhere in your `$PATH`. For Linux and macOS, a good place is generally `/usr/local/bin`. For Windows, there isn't a good place by default :(. 23 24## Homebrew 25 26For those with Homebrew, you'll need to `brew tap mike-engel/jwt-cli` repo to install it. 27 28```sh 29# Tap and install jwt-cli 30brew tap mike-engel/jwt-cli 31brew install jwt-cli 32 33# Ensure it worked ok by running the help command 34jwt help 35``` 36 37## Cargo 38 39If your system [supports](https://forge.rust-lang.org/platform-support.html) it, you can install via Cargo. Make sure you have Rust and Cargo installed, following [these instructions](https://www.rust-lang.org/tools/install) before proceeding. 40 41```sh 42cargo install jwt-cli 43``` 44 45The binary installs to your Cargo bin path (`~/.cargo/bin`). Make sure your `$PATH` environment variable includes this path. 46 47## FreshPorts 48 49If you're on FreeBSD, you can use the `pkg` tool to install `jwt-cli` on your system. 50 51```sh 52pkg install jwt-cli 53``` 54 55Big thanks to Sergey Osokin, the FreeBSD contributor who added `jwt-cli` to the FreeBSD ports tree! 56 57## GoFish 58 59`jwt-cli` is also available on Windows, macOS, and Linux using GoFish. 60See [gofi.sh](https://gofi.sh/index.html#install) for instructions for getting GoFish. 61 62After installing GoFish, run `jwt-cli` with: 63 64```sh 65gofish install jwt-cli 66``` 67 68# Usage 69 70For usage info, use the `help` command. 71 72```sh 73# top level help 74jwt help 75 76# command specific help 77jwt help encode 78``` 79 80## Usage as a pipe 81 82The `-` argument tells `jwt-cli` to read from standard input: 83 84```sh 85jwt encode --secret=fake '{"hello":"world"}' | jwt decode - 86``` 87 88It's useful when you're dealing with a chain of shell commands that produce a JWT. Pipe the result through `jwt decode -` to decode it. 89 90```sh 91curl <auth API> | jq -r .access_token | jwt decode - 92``` 93 94# Contributing 95 96I welcome all issues and pull requests! This is my first project in rust, so this project almost certainly could be better written. All I ask is that you follow the [code of conduct](code_of_conduct.md) and use [rustfmt](https://github.com/rust-lang-nursery/rustfmt) to have a consistent project code style. 97 98To get started you'll need `rustc` and `cargo` on your system. If they aren't already installed, I recommend [rustup](https://rustup.rs) to get both! 99 100## Running and building the project 101 102Once you have both installed you'll want to install the dependencies. 103 104```sh 105# install dependencies via cargo 106cargo update 107``` 108 109After that, I recommend running the tests and doing a debug build to make sure all is well from the start. 110 111```sh 112# run the tests 113cargo test 114 115# run a debug build 116cargo build 117 118# or, if you want, a release build 119cargo build --release 120``` 121 122If it built without any errors, you should be able to run the command via `cargo`. 123 124```sh 125cargo run -- help 126``` 127 128# [Code of conduct](code_of_conduct.md) 129 130# [Changelog](CHANGELOG.md) 131 132# [License](LICENSE.md) 133 134## Contributors ✨ 135 136Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): 137 138<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> 139<!-- prettier-ignore --> 140<table> 141 <tr> 142 <td align="center"><a href="https://www.mike-engel.com"><img src="https://avatars0.githubusercontent.com/u/464447?v=4" width="100px;" alt="Mike Engel"/><br /><sub><b>Mike Engel</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=mike-engel" title="Code">��</a> <a href="#question-mike-engel" title="Answering Questions">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=mike-engel" title="Documentation">��</a> <a href="#ideas-mike-engel" title="Ideas, Planning, & Feedback">��</a> <a href="#maintenance-mike-engel" title="Maintenance">��</a> <a href="#review-mike-engel" title="Reviewed Pull Requests">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=mike-engel" title="Tests">⚠️</a> <a href="https://github.com/mike-engel/jwt-cli/issues?q=author%3Amike-engel" title="Bug reports">��</a></td> 143 <td align="center"><a href="http://asymmetrical-view.com/"><img src="https://avatars0.githubusercontent.com/u/69799?v=4" width="100px;" alt="Kyle Burton"/><br /><sub><b>Kyle Burton</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=kyleburton" title="Code">��</a></td> 144 <td align="center"><a href="https://github.com/atschaef"><img src="https://avatars2.githubusercontent.com/u/6707250?v=4" width="100px;" alt="Aaron Schaef"/><br /><sub><b>Aaron Schaef</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=atschaef" title="Code">��</a></td> 145 <td align="center"><a href="https://github.com/hughsimpson"><img src="https://avatars2.githubusercontent.com/u/2494489?v=4" width="100px;" alt="hughsimpson"/><br /><sub><b>hughsimpson</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=hughsimpson" title="Code">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=hughsimpson" title="Tests">⚠️</a></td> 146 <td align="center"><a href="http://matkelly.com"><img src="https://avatars0.githubusercontent.com/u/2514780?v=4" width="100px;" alt="Mat Kelly"/><br /><sub><b>Mat Kelly</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=machawk1" title="Code">��</a> <a href="https://github.com/mike-engel/jwt-cli/issues?q=author%3Amachawk1" title="Bug reports">��</a></td> 147 <td align="center"><a href="http://www.jasonmfry.com"><img src="https://avatars3.githubusercontent.com/u/166681?v=4" width="100px;" alt="Jason"/><br /><sub><b>Jason</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/issues?q=author%3AJasonMFry" title="Bug reports">��</a></td> 148 <td align="center"><a href="https://crosscomm.com/"><img src="https://avatars1.githubusercontent.com/u/6886697?v=4" width="100px;" alt="Ben Berry"/><br /><sub><b>Ben Berry</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/issues?q=author%3Absberry" title="Bug reports">��</a></td> 149 </tr> 150 <tr> 151 <td align="center"><a href="https://medium.com/@therealklanni"><img src="https://avatars2.githubusercontent.com/u/626347?v=4" width="100px;" alt="Kevin Lanni"/><br /><sub><b>Kevin Lanni</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=therealklanni" title="Documentation">��</a></td> 152 <td align="center"><a href="https://github.com/kkrauth"><img src="https://avatars3.githubusercontent.com/u/680123?v=4" width="100px;" alt="Kosta Krauth"/><br /><sub><b>Kosta Krauth</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=kkrauth" title="Code">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=kkrauth" title="Tests">⚠️</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=kkrauth" title="Documentation">��</a></td> 153 <td align="center"><a href="https://github.com/codedust"><img src="https://avatars.githubusercontent.com/u/7175914?v=4" width="100px;" alt="codedust"/><br /><sub><b>codedust</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=codedust" title="Code">��</a> <a href="#ideas-codedust" title="Ideas, Planning, & Feedback">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=codedust" title="Tests">⚠️</a></td> 154 <td align="center"><a href="https://github.com/lizfeed"><img src="https://avatars.githubusercontent.com/u/61433510?v=4" width="100px;" alt="Liz Frost"/><br /><sub><b>Liz Frost</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=lizfeed" title="Code">��</a></td> 155 <td align="center"><a href="https://github.com/ceharris"><img src="https://avatars.githubusercontent.com/u/3943178?v=4" width="100px;" alt="Carl Harris"/><br /><sub><b>Carl Harris</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=ceharris" title="Code">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=ceharris" title="Tests">⚠️</a></td> 156 <td align="center"><a href="https://komi.dev"><img src="https://avatars.githubusercontent.com/u/27967726?v=4" width="100px;" alt="Yusuke Kominami"/><br /><sub><b>Yusuke Kominami</b></sub></a><br /><a href="https://github.com/mike-engel/jwt-cli/commits?author=komi1230" title="Code">��</a> <a href="https://github.com/mike-engel/jwt-cli/commits?author=komi1230" title="Documentation">��</a></td> 157 </tr> 158</table> 159 160<!-- ALL-CONTRIBUTORS-LIST:END --> 161 162This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! 163
){kind=link}
){kind=link}