DEV Community

Cover image for Stop pasting JWTs into random websites — I built a zero-dep CLI to decode them in your terminal
benjamin
benjamin

Posted on

Stop pasting JWTs into random websites — I built a zero-dep CLI to decode them in your terminal

#showdev #security #cli #opensource

You're debugging an auth issue. There's a JWT in a log line, or in an Authorization header you copied out of the network tab. You need to know two things: what's in it, and has it expired?

So you do what everyone does — paste it into jwt.io.

Stop for a second. That token is often a live credential. You just pasted it into a third-party web page: it's in your browser history, maybe in someone's logs, maybe cached. For a token that's still valid, that's a real problem.

The other option is the pipeline nobody can remember:

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python -m json.tool
Enter fullscreen mode Exit fullscreen mode

...which doesn't decode the header, doesn't tell you whether it's expired, breaks on base64url padding, and needs base64 -d on Linux but -D on macOS.

So I built jwtpeek: one command, fully offline, zero dependencies.

npx jwtpeek <token>
Enter fullscreen mode Exit fullscreen mode 
Header
  {
    "alg": "HS256",
    "typ": "JWT"
  }

Payload
  {
    "sub": "1234567890",
    "name": "John Doe",
    "exp": 1609459200
  }

Claims
  issued   2020-12-31 23:00:00 UTC  5y 166d ago
  expires  2021-01-01 00:00:00 UTC  EXPIRED 5y 166d ago
Enter fullscreen mode Exit fullscreen mode

It turns every time claim (exp, iat, nbf, auth_time, …) into a real date plus "expires in 3h 21m" / "EXPIRED 2d ago" — which is usually the actual answer you were after.

It fits how you already paste tokens 

pbpaste | jwtpeek                  # pipe it in
echo "$AUTH_HEADER" | jwtpeek      # a leading "Bearer " / "Authorization:" is stripped
jwtpeek "$t" --json | jq .payload  # machine-readable; stdout stays pure
Enter fullscreen mode Exit fullscreen mode

Decoded output goes to stdout; the "signature not verified" note goes to stderr, so piping into jq stays clean.

Script-friendly exit codes 

0   decoded OK and not expired (or no exp claim)
1   decoded OK but expired
2   not a valid JWT
Enter fullscreen mode Exit fullscreen mode 
jwtpeek "$TOKEN" >/dev/null 2>&1 && echo "still valid" || echo "expired or invalid"
Enter fullscreen mode Exit fullscreen mode

Decode, not verify — on purpose

The one thing I want to be loud about: jwtpeek does not check the signature. It shows you what a token says, not whether it's authentic. Verifying a signature needs the issuer's secret/public key, which is out of scope for a "what's in this thing" tool. Never make an authorization decision from decoded-but-unverified contents — jwtpeek prints a reminder on stderr every time.

A couple of design notes

  • Zero dependencies, both ecosystems. Node uses Buffer, Python uses base64/json/datetime. Nothing else — npx/pipx and it runs.
  • NumericDate is seconds per RFC 7519, but some issuers wrongly emit milliseconds. jwtpeek detects implausibly large values (a real seconds value won't reach 1e12 until the year 5138) and handles both.
  • The Node and Python ports are behavior-identical: same flags, same exit codes, byte-identical --json.

Install 

npx jwtpeek <token>        # Node >= 18
pip install jwtpeek        # Python >= 3.8
Enter fullscreen mode Exit fullscreen mode

How do you inspect tokens today — jwt.io, a base64 one-liner, an editor plugin? And would you actually want signature verification (bring-your-own-key) in a tool like this, or does that cross the line from "decoder" into "just do it properly in your app"? Curious what people think.

Top comments (0)