Command Line JWT Tools for Developers

Published: March 5, 2025 By: JWT Decode Team Category: Developer Tools

JSON Web Tokens (JWTs) have become the standard for modern API authentication, but working with them can be challenging. Command-line tools offer developers a quick and efficient way to decode, verify, and manage JWTs right from the terminal. This guide explores the best CLI tools that will boost your productivity when working with JWTs.

Table of Contents

Why Use Command Line Tools for JWT?

While web-based tools like JWT Decode Online offer convenience, command-line tools provide distinct advantages for developers:

Speed & Efficiency

Quickly decode or verify tokens without switching context from your terminal.

Automation

Easily incorporate JWT operations into scripts and CI/CD pipelines.

Security

Keep sensitive tokens local to your machine, reducing exposure risk.

Integration

Easily pipe JWT operations with other command-line tools for powerful workflows.

Essential JWT CLI Tools

Let's explore the most useful command-line tools for working with JWTs:

Tool Language Key Features Best For
jwt-cli Rust/Node.js Decoding, encoding, verification General-purpose JWT operations
jq + base64 Shell Lightweight decoding, JSON processing Quick inspections without installation
jose Node.js Advanced cryptographic operations Complex JWT/JWS/JWE operations
pyjwt Python Python-based JWT handling Python developers, scripting
OpenSSL C Key generation, manual verification Cryptographic operations

JWT-CLI: The Swiss Army Knife

JWT-CLI is arguably the most user-friendly dedicated JWT tool for the command line. It's fast, feature-rich, and available for most platforms.

Installation

# Using npm (Node.js version)
npm install -g jwt-cli

# Using Homebrew (macOS)
brew install mike-engel/jwt-cli/jwt-cli

# Using Cargo (Rust version)
cargo install jwt-cli

Basic Usage

# Decode a JWT
jwt decode eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

# Encode a new JWT
jwt encode --secret your-secret-key --payload '{"sub": "1234567890", "name": "John Doe", "iat": 1516239022}'

# Verify a JWT with a secret
jwt verify --secret your-secret-key eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Advanced Features

JWT-CLI offers several advanced features, including:

  • Support for different algorithms (HS256, RS256, etc.)
  • RSA and ECDSA key pair support
  • Pretty-printing of JWT claims
  • Colorized output
  • Detailed expiration information
# Using RS256 with a private key
jwt encode --alg RS256 --secret ./private-key.pem --payload '{"sub": "1234567890"}'

# Verifying with a public key
jwt verify --alg RS256 --secret ./public-key.pem [TOKEN]

JQ + Base64: Native Decoding

For those who prefer lightweight solutions using standard Unix tools, JWTs can be decoded with a combination of base64 and jq:

Note: This approach doesn't verify the JWT signature but is excellent for quick inspections.

Basic Decoding

# Create a shell function for JWT decoding
function jwt-decode() {
    jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "$1"
}

# Usage
jwt-decode eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

For a one-liner that doesn't require a function definition:

# Decode JWT header
echo -n "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" | base64 -d | jq

# Decode JWT payload (may need to add padding)
echo -n "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ" | base64 -d | jq
Important: JWT base64url encoding might require handling of padding and replacing characters before decoding. The function above handles this automatically.

Advanced JQ Processing

JQ's power comes from its ability to process and transform JSON. Here's how to extract specific claims:

# Extract only the 'sub' claim from payload
function jwt-extract-sub() {
    jq -R 'split(".") | .[1] | @base64d | fromjson | .sub' <<< "$1"
}

# Check if a token is expired
function jwt-is-expired() {
    local exp=$(jq -R 'split(".") | .[1] | @base64d | fromjson | .exp' <<< "$1")
    local now=$(date +%s)
    
    if [[ $exp -lt $now ]]; then
        echo "Token expired at $(date -d @$exp)"
        return 0
    else
        echo "Token valid until $(date -d @$exp)"
        return 1
    fi
}

JOSE Tools for Advanced Cryptography

The JOSE (JavaScript Object Signing and Encryption) toolkit provides comprehensive support for advanced JWT operations:

Installation

# Install Node.js JOSE CLI
npm install -g jose-cli

Key Features

  • Complete support for JWS (JSON Web Signature)
  • Support for JWE (JSON Web Encryption)
  • Key generation and management
  • JWKS (JSON Web Key Set) handling
  • Support for all standard algorithms
# Generate a JWT with jose
jose sign --alg HS256 --secret your-secret-key '{"sub": "user123", "role": "admin"}'

# Verify a JWT
jose verify --alg HS256 --secret your-secret-key "your.jwt.token"

# Generate an RSA key pair
jose generate-key-pair --alg RS256 --use sig --output-public public.jwk --output-private private.jwk

# Create a JWT using RSA
jose sign --alg RS256 --key private.jwk '{"sub": "user123"}'

Encrypted JWTs

One of JOSE's standout features is its support for JWE (encrypted tokens):

# Encrypt a JWT payload
jose encrypt --alg RSA-OAEP-256 --enc A256GCM --key public.jwk '{"sensitive": "data"}'

# Decrypt a JWE
jose decrypt --key private.jwk "encrypted.token"

OpenSSL for JWT Verification

OpenSSL is a powerful tool for working with cryptography, including JWT signature verification:

Manual Verification with OpenSSL

# For RS256 tokens - Verify signature manually
# 1. Extract header and payload
HEADER_PAYLOAD=$(echo -n "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0" | tr -d '=')

# 2. Extract the signature
SIGNATURE=$(echo -n "c4hiUPoj9qkSMuTIm9NHKeoQHkFsnoGTdNN6DfJI..." | base64 -d | xxd -p -c 256)

# 3. Verify using OpenSSL
echo -n $HEADER_PAYLOAD | openssl dgst -sha256 -verify public.pem -signature <(echo $SIGNATURE | xxd -r -p)

Generate Keys for JWT

# Generate a private key
openssl genrsa -out private.pem 2048

# Extract the public key
openssl rsa -in private.pem -pubout -out public.pem
Tip: While OpenSSL is powerful, dedicated JWT tools are generally easier to use for standard tasks. OpenSSL is best for key management and custom cryptographic operations.

Creating Custom JWT Scripts

For specialized workflows, creating custom scripts can be highly effective. Here's a simple but powerful Bash script that combines several tools:

#!/bin/bash
# jwt-tools.sh - Custom JWT toolkit

function jwt-help {
    echo "JWT Command Line Tools"
    echo "---------------------"
    echo "Usage:"
    echo "  jwt-tools decode           - Decode JWT without verification"
    echo "  jwt-tools verify   - Verify JWT signature"
    echo "  jwt-tools check-exp        - Check if JWT is expired"
    echo "  jwt-tools extract   - Extract specific claim"
}

function jwt-decode {
    local token=$1
    local header=$(echo -n ${token%.*.*} | base64 -d 2>/dev/null || echo "Invalid header")
    local payload=$(echo -n ${token#*.} | cut -d. -f1 | base64 -d 2>/dev/null || echo "Invalid payload")
    
    echo "Header:"
    echo $header | jq . || echo $header
    echo -e "\nPayload:"
    echo $payload | jq . || echo $payload
}

function jwt-verify {
    # Simplified verification - use a proper library for production
    local token=$1
    local secret=$2
    
    # Implementation depends on algorithm
    # This is a simplified example
    echo "Verification would happen here"
}

function jwt-check-exp {
    local token=$1
    local payload=$(echo -n ${token#*.} | cut -d. -f1 | base64 -d 2>/dev/null)
    
    # Extract exp claim
    local exp=$(echo $payload | jq -r '.exp // empty')
    
    if [[ -z "$exp" ]]; then
        echo "No expiration claim found"
        return
    fi
    
    local now=$(date +%s)
    
    if [[ $exp -lt $now ]]; then
        echo "TOKEN EXPIRED at $(date -d @$exp)"
        return 1
    else
        local diff=$((exp - now))
        echo "Token valid for $diff more seconds (expires $(date -d @$exp))"
        return 0
    fi
}

function jwt-extract {
    local token=$1
    local claim=$2
    
    local payload=$(echo -n ${token#*.} | cut -d. -f1 | base64 -d 2>/dev/null)
    echo $payload | jq -r ".$claim // \"Claim not found\""
}

# Main command router
case "$1" in
    decode)
        jwt-decode "$2"
        ;;
    verify)
        jwt-verify "$2" "$3"
        ;;
    check-exp)
        jwt-check-exp "$2"
        ;;
    extract)
        jwt-extract "$2" "$3"
        ;;
    *)
        jwt-help
        ;;
esac

Using Python for Custom Scripts

For more complex processing, Python with the PyJWT library offers a good balance of readability and power:

#!/usr/bin/env python3
# jwt_tool.py

import jwt
import sys
import json
import time
from datetime import datetime

def decode_token(token, verify=False, secret=None):
    try:
        if verify and secret:
            decoded = jwt.decode(token, secret, algorithms=["HS256"])
            print("✓ Signature verified")
        else:
            decoded = jwt.decode(token, options={"verify_signature": False})
            print("⚠ Token decoded without signature verification")
            
        header = jwt.get_unverified_header(token)
        
        print("\nHEADER:")
        print(json.dumps(header, indent=2))
        
        print("\nPAYLOAD:")
        print(json.dumps(decoded, indent=2))
        
        # Check expiration
        if 'exp' in decoded:
            exp_time = datetime.fromtimestamp(decoded['exp'])
            now = datetime.now()
            if exp_time > now:
                print(f"\nToken expires at: {exp_time} (valid for {(exp_time - now).total_seconds()} seconds)")
            else:
                print(f"\n⚠ Token EXPIRED at: {exp_time}")
    
    except jwt.ExpiredSignatureError:
        print("❌ Token has expired")
    except jwt.InvalidTokenError as e:
        print(f"❌ Invalid token: {e}")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: jwt_tool.py  [--verify] [--secret SECRET]")
        sys.exit(1)
        
    token = sys.argv[1]
    verify = "--verify" in sys.argv
    
    secret = None
    if "--secret" in sys.argv:
        secret_index = sys.argv.index("--secret") + 1
        if secret_index < len(sys.argv):
            secret = sys.argv[secret_index]
    
    decode_token(token, verify, secret)
Pro Tip: Make your script executable (chmod +x jwt_tool.py) and add it to your PATH for easy access from anywhere in your terminal.

Best Practices and Workflow Tips

Here are some tips for working efficiently with JWT command-line tools:

Recommended Workflow

  1. Keep tokens in environment variables for easy access without exposing them in command history
  2. Create token templates for testing different scenarios
  3. Use aliases for common JWT operations in your shell configuration
  4. Combine with other tools like curl for API testing
  5. Store keys securely with tools like keyring or pass

Security Considerations

  • Be cautious with command history when working with sensitive tokens
  • Use HISTIGNORE in bash to prevent storing certain commands
  • Don't hardcode secrets in scripts
  • Verify signatures when handling user-supplied tokens
# Add to .bashrc or .zshrc for safer JWT operations
export HISTIGNORE="*jwt*"

# Store JWT in environment variable
export MY_JWT="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.Rq8IxqeIVXgw1beavDuBkopHNUlz1XM2SVi-kOU-uKY"

# Use with curl
curl -H "Authorization: Bearer $MY_JWT" https://api.example.com/protected-resource

Integration with Development Workflow

JWT tools can be integrated into your development workflow for more efficient testing:

# Generate a test token for local development
function dev-token() {
    local payload="{\"sub\":\"developer\",\"role\":\"admin\",\"exp\":$(($(date +%s) + 3600))}"
    jwt encode --secret development-secret --payload "$payload"
}

# Test API with generated token
function test-api() {
    local token=$(dev-token)
    curl -H "Authorization: Bearer $token" http://localhost:3000/api/protected
}

Conclusion

Command-line JWT tools are an invaluable addition to any developer's toolkit. They provide quick, efficient ways to work with JWTs without leaving your terminal, enabling faster debugging and more streamlined workflows.

For most developers, we recommend starting with jwt-cli for its balance of features and ease of use. As your needs grow, explore the other tools mentioned in this article to find the perfect fit for your specific requirements.

Remember that while these tools make JWT handling easier, it's still essential to understand the security implications of JWT usage in your applications. Always follow best practices for token management, especially when dealing with authentication and authorization.

Related Articles

Understanding JWT in React Applications

Learn how to implement JWT authentication in React apps for secure user sessions.

Read More
JWT Authentication in Flutter Apps

Step-by-step guide to implementing JWT authentication in your Flutter applications.

Read More
JWT vs Session Tokens: Which to Choose?

A detailed comparison of JWT and session-based authentication approaches.

Read More