clerk-cli

A fast, intelligent command-line interface for the Clerk authentication platform.

Installation

Homebrew (macOS/Linux)

brew install osodevops/tap/clerk

Cargo

cargo install --git https://github.com/osodevops/clerk-cli

GitHub Releases

Download pre-built binaries from the Releases page.

Quick Start

1. Set Your Secret Key

export CLERK_SECRET_KEY=sk_live_...

# Or store it persistently
clerk auth login --secret-key sk_live_abc123

2. Explore

# List users
clerk users list
clerk users list --email alice@example.com --output json

# Get a specific user
clerk users get user_abc123

# List organizations
clerk organizations list --output csv

# Manage sessions
clerk sessions list --user-id user_abc123 --status active

# View instance settings
clerk whoami

3. Manage Profiles

# Store credentials for different environments
clerk auth login --secret-key sk_live_... --profile production
clerk auth login --secret-key sk_test_... --profile development

# Use a profile for a single command
clerk users list --profile production

# Switch default profile
clerk auth switch-profile development

# Compare environments
clerk diff production development

4. Power Features

# Decode a JWT
clerk jwt decode eyJhbGciOiJSUzI1NiJ9...

# Verify JWT signature against JWKS
clerk jwt verify eyJhbGciOiJSUzI1NiJ9...

# Export all users to CSV
clerk export users --format csv --output-file users.csv

# Import users from JSON
clerk import users --file new_users.json

# Watch for new users in real-time
clerk watch users --since 5m --interval 10

# Seed test data
clerk seed users --count 10
clerk seed clean

# Test webhooks locally
clerk webhooks test --event user.created --url http://localhost:3000/webhook

Output Formats

# Table (default for terminal)
clerk users list

# JSON (default for pipes)
clerk users list --output json

# CSV
clerk users list --output csv

# YAML
clerk users list --output yaml

# Compact JSON
clerk users list --output json --compact

Configuration

Config file: ~/.config/clerk-cli/config.toml

[default]
active_profile = "production"
output_format = "table"
page_size = 100

[auth]
secret_key = "sk_live_..."
callback_port = 8080

[cache]
enabled = true
list_ttl_secs = 300
get_ttl_secs = 900
max_size_mb = 50

[rate_limit]
calls_per_10_seconds = 1000
dev_calls_per_10_seconds = 100
max_concurrent = 10

[profiles.production]
secret_key = "sk_live_..."
instance_name = "My App (Production)"
api_version = "2025-11-10"

[profiles.development]
secret_key = "sk_test_..."
instance_name = "My App (Development)"

Shell Completions

# Bash
clerk completions bash > ~/.local/share/bash-completion/completions/clerk

# Zsh
clerk completions zsh > ~/.zfunc/_clerk

# Fish
clerk completions fish > ~/.config/fish/completions/clerk.fish

Environment Variables

Variable	Description
CLERK_SECRET_KEY	Clerk Backend API secret key (sk_live_... or sk_test_...)
CLERK_PROFILE	Active profile name (overrides config file)
CLERK_OUTPUT	Default output format: table, json, csv, yaml
CLERK_API_VERSION	API version header (default: 2025-11-10)
CLERK_CONFIG	Config file path override
CLERK_BASE_URL	Override the Clerk API base URL
NO_COLOR	Disable ANSI color output (any value)

License

MIT