inngest-ctl Reference

A CLI tool for interacting with Inngest events and function runs.

IMPORTANT: ALWAYS use inngest-ctl for Inngest operations. NEVER fall back to raw curl commands, direct fetch calls, or constructing HTTP requests manually. The CLI handles authentication, URL construction, and response formatting automatically.

Setup

Running the CLI

# Via bunx (no install needed)
bunx @ctdio/inngest-ctl <command>

# Or create an alias
alias inngest-ctl="bunx @ctdio/inngest-ctl"

Environment Variables (Required)

export INNGEST_EVENT_KEY="your-event-key"      # For sending events
export INNGEST_SIGNING_KEY="your-signing-key"  # For API queries

For Local Dev Server

Use --dev flag:

inngest-ctl events list --dev --pretty

Override URL:

export INNGEST_DEV_URL="http://localhost:9000"

Commands

List Events

inngest-ctl events list [--name <name>] [--limit <n>] [--pretty] [--dev]

Examples:

inngest-ctl events list --pretty
inngest-ctl events list --name "user.signup" --limit 10 --pretty
inngest-ctl events list --dev --pretty

Send Event

inngest-ctl events send --name "<name>" --data '<json>' [--id <id>] [--env <env>] [--dev]
inngest-ctl events send --name "<name>" --data-file <path> [--id <id>] [--env <env>] [--dev]

Providing event data — use a heredoc for anything beyond trivial payloads:

Heredoc (recommended — single command, no escaping issues):

inngest-ctl events send --name "order.created" --data "$(cat <<'EOF'
{
  "orderId": "ord-123",
  "items": [
    {"sku": "WIDGET-1", "qty": 2, "price": 9.99},
    {"sku": "GADGET-3", "qty": 1, "price": 24.50}
  ],
  "customer": {
    "id": "cust-456",
    "email": "user@example.com"
  }
}
EOF
)" --dev

Inline JSON (only for simple, flat payloads):

inngest-ctl events send --name "user.signup" --data '{"userId": "123"}' --dev

--data-file (when JSON already exists on disk):

inngest-ctl events send --name "user.signup" --data-file /tmp/event-data.json --dev

More send examples:

# Simple payload — inline is fine
inngest-ctl events send --name "test.event" --data '{}' --dev

# With deduplication ID
inngest-ctl events send --name "user.signup" --data '{"userId": "u1"}' --id "dedup-123"

# With branch environment
inngest-ctl events send --name "order.created" --data '{"orderId": "o1"}' --env "feature/my-branch"

# Nested payload — use heredoc
inngest-ctl events send --name "user.created" --data "$(cat <<'EOF'
{
  "userId": "u-789",
  "profile": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "roles": ["admin", "editor"]
  }
}
EOF
)" --dev

Get Event Details

inngest-ctl events get <event-id> [--pretty] [--dev]

Example:

inngest-ctl events get 01H08W4TMBNKMEWFD0TYC532GG --pretty

List Runs for Event

inngest-ctl events runs <event-id> [--pretty] [--dev]

Example:

inngest-ctl events runs 01H08W4TMBNKMEWFD0TYC532GG --pretty

Get Run Status

Monitor run status and duration.

inngest-ctl runs status <run-id> [--pretty] [--dev]

Example:

inngest-ctl runs status 01H08W5TMBNKMEWFD0TYC532GH --pretty

Get Run Details (Jobs/Steps)

inngest-ctl runs get <run-id> [--pretty] [--dev]

Example:

inngest-ctl runs get 01H08W5TMBNKMEWFD0TYC532GH --pretty

List Runs by Event

inngest-ctl runs list --event <event-id> [--pretty] [--dev]

Example:

inngest-ctl runs list --event 01H08W4TMBNKMEWFD0TYC532GG --pretty

Cancel Runs

inngest-ctl cancel --app <app> --function <fn> --started-after <time> --started-before <time> [--if <expr>]

Example:

inngest-ctl cancel --app my-app --function my-func --started-after 1h --started-before now

Global Flags

Common Workflows

Local Development

# Start Inngest dev server
npx inngest-cli@latest dev

# List local events
inngest-ctl events list --dev --pretty

# Send test event
inngest-ctl events send --name "test.event" --data '{"test": true}' --dev

# Check what runs it triggered
inngest-ctl events runs <event-id> --dev --pretty

# Monitor run status
inngest-ctl runs status <run-id> --dev --pretty

Debugging Function Runs

# 1. Find recent events
inngest-ctl events list --pretty

# 2. Get event details
inngest-ctl events get <event-id> --pretty

# 3. List runs triggered by the event
inngest-ctl events runs <event-id> --pretty

# 4. Check run status and duration
inngest-ctl runs status <run-id> --pretty

# 5. Get detailed job/step info
inngest-ctl runs get <run-id> --pretty

Production Monitoring

# List recent events for a specific type
inngest-ctl events list --name "user.signup" --limit 50 --pretty

# Check if a specific run completed
inngest-ctl runs status <run-id> --pretty

# Export event data for analysis
inngest-ctl events list --limit 100 --output events.json

Output Format

Default output is JSON. Use --pretty for colored human-readable output:

• Event names colored by type:
  • Red: error/fail events
  • Green: success/complete events
  • Yellow: warn events
  • Blue: default
• Run status badges: [OK], [ERR], [RUN]
• Durations show “(running)” for active runs
• Timestamps in gray