JWTop

JWT operations CLI. Decode, verify, create, and sign JSON Web Tokens.

## CLI Usage

### decode

Decode and pretty-print a JWT without verifying the signature.

``sh
jwtop decode <token>
`

Output: Header, Claims, and Signature printed as formatted JSON.

`sh
jwtop decode eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5NXgL0n3I9PlFUP0THsR8U
`

`
Header:
{
"alg": "HS256",
"typ": "JWT"
}

Claims:
{
"sub": "1234567890"
}

Signature:
dozjgNryP4J3jVmNHl0w5NXgL0n3I9PlFUP0THsR8U
`

---

### verify

Verify a JWT signature and print its claims. Exits with code 1 if the token is invalid.

`sh
jwtop verify <token> [--secret <secret>] [--key <pem-file>] [--jwks <uri>]
`

| Flag | Description |
|------|-------------|
| --secret | HMAC secret string |
| --key | Path to PEM public (or private) key file |
| --jwks | JWKS endpoint URI |

Examples:

`sh
# HMAC
jwtop verify $TOKEN --secret mysecret

# RSA/EC public key
jwtop verify $TOKEN --key /path/to/public.pem

# JWKS endpoint
jwtop verify $TOKEN --jwks https://example.com/.well-known/jwks.json
`

---

### create

Create and sign a new JWT.

`sh
jwtop create --alg <alg> (--secret <secret> | --key <pem-file>) [options]
`

| Flag | Description |
|------|-------------|
| --alg | Signing algorithm, e.g. HS256, RS256, ES256 (required) |
| --secret | HMAC secret string |
| --key | Path to PEM private key file |
| --claim key=value | Custom claim (repeatable) |
| --sub | Subject claim |
| --iss | Issuer claim |
| --aud | Audience claim |
| --exp | Expiration duration, e.g. 1h, 30m |
| --iat | Include issued-at (iat) claim |

Claim values are auto-parsed: integers and booleans are stored as their native types; everything else is stored as a string.

Examples:

`sh
# HS256 with claims
jwtop create --alg HS256 --secret mysecret \
--sub user123 --iss myapp --exp 1h --iat \
--claim role=admin --claim plan=pro

# RS256 with a private key
jwtop create --alg RS256 --key /path/to/private.pem \
--sub user123 --exp 24h
`

---

### sign

Re-sign an existing JWT with a new algorithm or key. The original claims are preserved.

`sh
jwtop sign <token> --alg <alg> (--secret <secret> | --key <pem-file>)
`

| Flag | Description |
|------|-------------|
| --alg | Target signing algorithm, or none (required) |
| --secret | HMAC secret string |
| --key | Path to PEM private key file |

Examples:

`sh
# Change algorithm and key
jwtop sign $TOKEN --alg RS256 --key /path/to/private.pem

# Strip signature (alg=none)
jwtop sign $TOKEN --alg none
`

---

### version

Print the build version.

`sh
jwtop version
``

---