CLI

The Unkey CLI gives you direct access to the Unkey API from your terminal. Create and manage API keys, configure rate limits, set permissions, and query analytics, all without leaving the command line.

Installation#

npm install -g unkey

# macOS (Apple Silicon)curl -L https://github.com/unkeyed/unkey/releases/latest/download/unkey_darwin_arm64 -o unkeychmod +x unkeysudo mv unkey /usr/local/bin/

Authentication#

Before using the CLI, authenticate with your root key:

unkey auth login

This stores your key at ~/.unkey/config.toml. All subsequent commands use it automatically.

You can also pass a key per-command or via environment variable:

# Flagunkey api keys create-key --root-key=unkey_xxx --api-id=api_123# Environment variableexport UNKEY_ROOT_KEY=unkey_xxxunkey api keys create-key --api-id=api_123

Usage#

All API operations live under the unkey api command, organized by resource:

unkey api <resource> <action> [flags]

Resources#

Examples#

Create an API and issue a key:

unkey api apis create-api --name=payment-service-produnkey api keys create-key --api-id=api_1234abcd --name='Production Key' --enabled

Verify a key:

unkey api keys verify-key --key=sk_1234abcdef

Set up rate limiting:

unkey api ratelimit limit --namespace=api.requests --identifier=user_123 --limit=100 --duration=60000

Query analytics:

unkey api analytics get-verifications --query="SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = 'VALID' AND time >= now() - INTERVAL 7 DAY"

Manage permissions:

unkey api permissions create-permission --name=documents.read --slug=documents-readunkey api keys add-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write

Output#

By default, the CLI prints the request ID, followed by the response data:

req_2c9a0jf23l4k567{  "id": "api_1234abcd",  "name": "payment-service-prod"}

For scripting, use --output=json to get the raw API response envelope (meta + data) as JSON on stdout:

unkey api apis create-api --name=my-api --output=json | jq '.data.id'

Send a typed JSON body#

Every unkey api action accepts --body for sending a JSON string directly to the API. This is useful for AI agents and scripts that already produce an API request body:

REQUEST_BODY='{"apiId":"api_1234abcd","name":"Agent-created key"}'unkey api keys create-key --body="$REQUEST_BODY" --output=json

Explicitly passing --body selects typed body mode. The CLI decodes the value into the endpoint's generated SDK request type, then the SDK serializes that typed request. Malformed JSON is rejected locally. An explicitly empty value, including --body='', selects body mode and is rejected as malformed JSON. Request schema and business validation remain the API's responsibility.

You cannot combine --body with request-building flags. Selecting body mode waives required request-building flag checks because the typed JSON supplies the request instead.

Operational flags continue to work in body mode. Your configured root key or --root-key is still used, while --api-url and --output keep their normal behavior.

Quote the JSON so your shell passes it as one argument. Single quotes are usually the clearest choice for inline JSON in Bash:

unkey api apis create-api \  --body='{"name":"payment-service-prod"}'

Global Flags#

Every command accepts these flags:

Help#

Every command has built-in help with descriptions, flag details, and examples:

unkey --helpunkey api --helpunkey api keys --helpunkey api keys create-key --help