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

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

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

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

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

jwtpeek "$TOKEN" >/dev/null 2>&1 && echo "still valid" || echo "expired or invalid"

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

• npm: https://www.npmjs.com/package/jwtpeek
• PyPI: https://pypi.org/project/jwtpeek
• GitHub: https://github.com/jjdoor/jwtpeek

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.