A fast, simple, and powerful command-line tool for creating, decoding, and inspecting JWT (JSON Web Tokens). Built with Go and Cobra.
- Sign JWT tokens with HMAC algorithms (HS256, HS384, HS512)
- Decode and verify JWT tokens with signature validation
- Inspect tokens without verification (like jwt.io)
- Human-friendly time parsing - Use
1d,5min,+30m,+7dfor expiration times - Beautiful table output - Clean, styled output using lipgloss
- JSON output option - Machine-readable output for automation
- Standard JWT claims - Support for iss, sub, aud, exp, nbf, iat, jti
- Auto-generate JTI - UUID-style JWT ID generation
- Cross-platform - Works on Linux, macOS, and Windows
- Installation
- Quick Start
- Usage
- Examples
- Time Formats
- Algorithms
- Building from Source
- Contributing
- Security
- License
go install github.com/lazhari/jwt@latestbrew install lazhari/tap/jwtDownload the latest release for your platform from the releases page.
git clone https://github.com/lazhari/jwt.git
cd jwt
make build
# Binary will be in bin/jwt# Sign a JWT token
jwt sign --payload '{"user_id":123,"role":"admin"}' --secret "your-secret-key" --exp "+1h"
# Decode and verify a JWT
jwt decode YOUR_TOKEN_HERE --secret "your-secret-key"
# Inspect a JWT without verification
jwt inspect YOUR_TOKEN_HERECreate and sign a new JWT token.
jwt sign --payload '{"user_id":123}' --secret "my-secret-key"jwt sign \
--payload '{"user_id":123}' \
--secret "my-secret-key" \
--iss "https://example.com" \
--sub "user123" \
--aud "https://api.example.com" \
--exp "+1h" \
--jti-auto| Flag | Description | Example |
|---|---|---|
--payload |
JSON payload (required) | '{"user_id":123}' |
--secret |
Secret key for signing (required) | "my-secret-key" |
--alg |
Algorithm (default: HS256) | HS256, HS384, HS512 |
--iss |
Issuer claim | "https://example.com" |
--sub |
Subject claim | "user123" |
--aud |
Audience claim (repeatable) | "https://api.example.com" |
--exp |
Expiration time | "+1h", "1609459200", "2024-01-01T00:00:00Z" |
--nbf |
Not Before time | "+5m", "1609459200" |
--iat |
Issued At time (default: now) | "now", "1609459200" |
--no-iat |
Omit Issued At claim | (boolean flag) |
--jti |
JWT ID | "unique-id-123" |
--jti-auto |
Auto-generate JWT ID | (boolean flag) |
Decode and verify a JWT token.
jwt decode YOUR_TOKEN --secret "my-secret-key"jwt decode YOUR_TOKEN --secret "my-secret-key" --json| Flag | Description |
|---|---|
--secret |
Secret key for verification (required) |
--json |
Output in JSON format |
Inspect a JWT token without verification (no secret required).
jwt inspect YOUR_TOKENjwt inspect YOUR_TOKEN --json| Flag | Description |
|---|---|
--json |
Output in JSON format |
jwt sign \
--payload '{"user_id":123,"email":"[email protected]"}' \
--secret "super-secret-key" \
--exp "+1h"jwt sign \
--payload '{"data":"important"}' \
--secret "my-secret" \
--iss "auth-service" \
--sub "user-456" \
--aud "api-service" \
--aud "web-app" \
--exp "+7d" \
--jti-autoTOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjN9.abc123"
jwt decode $TOKEN --secret "my-secret"# Useful for debugging or examining tokens when you don't have the secret
jwt inspect $TOKEN# More secure than passing secrets on command line
export JWT_SECRET="my-secret-key"
jwt sign --payload '{"user_id":123}' --secret "$JWT_SECRET"# Create a token for API testing
TOKEN=$(jwt sign --payload '{"user_id":999,"role":"admin"}' --secret "test-key" --exp "+1d")
echo "Authorization: Bearer $TOKEN"
# Use with curl
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/protectedThe --exp, --nbf, and --iat flags support multiple time formats:
--exp "+1h" # 1 hour from now
--exp "+30m" # 30 minutes from now
--exp "+7d" # 7 days from now
--exp "+60s" # 60 seconds from now
--nbf "+5min" # 5 minutes from now (alternative syntax)Supported units: d (days), h (hours), m/min (minutes), s/sec (seconds)
--exp "1609459200"--exp "2024-12-31T23:59:59Z"
--exp "2024-06-15T10:30:00+02:00"Currently supported HMAC algorithms:
| Algorithm | Description | Key Size |
|---|---|---|
| HS256 | HMAC-SHA256 (default) | 256 bits (32 bytes) |
| HS384 | HMAC-SHA384 | 384 bits (48 bytes) |
| HS512 | HMAC-SHA512 | 512 bits (64 bytes) |
# Generate a strong secret (32 bytes for HS256)
openssl rand -base64 32
# Or use /dev/urandom
head -c 32 /dev/urandom | base64- Go 1.21 or later
- Make (optional, for using Makefile)
# Clone the repository
git clone https://github.com/lazhari/jwt.git
cd jwt
# Using Make
make build
# Or using Go directly
go build -o jwt .# Using Make
make test
# With coverage
make test-coverage
# Or using Go directly
go test ./...make help # Show all available targets
make build # Build the binary
make install # Install to GOPATH/bin
make test # Run tests
make test-coverage # Run tests with coverage
make lint # Run golangci-lint
make fmt # Format code
make clean # Remove build artifactsWe welcome contributions! Please see CONTRIBUTING.md for details on:
- Setting up your development environment
- Code style guidelines
- Submitting pull requests
- Reporting bugs
- Requesting features
Quick contribution steps:
- Fork the repository
- Create your feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run tests:
make test - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Protect your secrets:
- Use environment variables instead of command-line arguments
export JWT_SECRET="my-secret-key" jwt sign --payload '{"user_id":123}' --secret "$JWT_SECRET"
- Generate strong secrets:
openssl rand -base64 32 - Never commit secrets to version control
Token validation:
- Always verify tokens with
decodecommand using the correct secret - Use
inspectonly for debugging (it doesn't verify signatures) - Set appropriate expiration times with
--exp
For security issues, please open a GitHub issue.
Planned features for future releases:
- RSA algorithm support (RS256, RS384, RS512)
- ECDSA algorithm support (ES256, ES384, ES512)
- Read secrets from files (
--secret-file) - Interactive secret input
- Config file support
- Shell completion (bash, zsh, fish)
- Token validation with custom claims
- Batch token operations
- Key generation utility
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with Cobra - CLI framework
- JWT implementation by golang-jwt/jwt
- Beautiful terminal output by Charm - Lipgloss
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: GitHub Wiki
Made with ❤️ by Lazhari