@lxgicstudios/jwt-decode

Decode and inspect JWT tokens from the command line.

See what's inside your tokens. Check if they're expired. No more jwt.io tabs.

Installation

# Use directly with npx (recommended)
npx @lxgicstudios/jwt-decode <token>

# Or install globally
npm install -g @lxgicstudios/jwt-decode

Usage

# Decode a token
npx @lxgicstudios/jwt-decode eyJhbGciOiJIUzI1NiIs...

# Works with "Bearer " prefix
npx @lxgicstudios/jwt-decode "Bearer eyJhbGci..."

# Pipe from env var
echo $AUTH_TOKEN | npx @lxgicstudios/jwt-decode

# Read from file
npx @lxgicstudios/jwt-decode -f token.txt

# Check if expired (for scripts)
npx @lxgicstudios/jwt-decode --check $TOKEN && echo "Valid"

Example Output

Header
──────
  alg: "HS256"
  typ: "JWT"

Payload
───────
  sub: "1234567890"
  name: "John Doe"
  email: "[email protected]"
  iat: 1706547200 (2024-01-29T16:00:00.000Z)
  exp: 1706633600 (2024-01-30T16:00:00.000Z)

Status
──────
  Valid - expires in 23 hours
  Issued: 2024-01-29T16:00:00.000Z

Options

| Option | Description | |--------|-------------| | -f, --file <path> | Read token from file | | -c, --claim <name> | Extract specific claim only | | --header | Show only header | | --payload | Show only payload | | --json | Output as JSON | | --check | Check expiration (exit 1 if expired) | | -h, --help | Show help |

Examples

# Extract user ID
npx @lxgicstudios/jwt-decode -c sub $TOKEN

# Get expiration as JSON
npx @lxgicstudios/jwt-decode --json $TOKEN | jq .expiresIn

# Use in scripts
if npx @lxgicstudios/jwt-decode --check $TOKEN 2>/dev/null; then
  echo "Token is valid"
else
  echo "Token expired, refreshing..."
fi

Programmatic API

import { 
  decodeJwt, 
  getJwtExpiration, 
  getJwtClaim, 
  isValidJwtStructure 
} from '@lxgicstudios/jwt-decode';

// Decode full token
const decoded = decodeJwt(token);
console.log(decoded.payload.sub);
console.log(decoded.isExpired);

// Get expiration info
const { isExpired, expiresAt, timeRemaining } = getJwtExpiration(token);

// Extract specific claim
const userId = getJwtClaim<string>(token, 'sub');

// Validate structure
if (isValidJwtStructure(token)) {
  // Token is well-formed (doesn't verify signature)
}

Features

• ✅ Colored, readable output
• ✅ Automatic "Bearer " prefix handling
• ✅ Human-readable expiration times
• ✅ Timestamp conversion
• ✅ Pipe support
• ✅ Script-friendly exit codes
• ✅ JSON output mode

Built by LXGIC Studios

🔗 GitHub · Twitter