Inngest CLI

A powerful CLI for managing Inngest jobs with support for watching, canceling, and filtering by status.

Features

• Query run status by run ID or event ID with detailed output
• List runs with filtering by status, function, and pagination support
• Watch runs in real-time with configurable polling intervals and timeouts
• Cancel runs individually or in bulk with conditional expressions and dry-run mode
• View job details for step-by-step execution analysis and debugging
• Complete debugging context with input data and output for failed runs
• Rich terminal output with colors, tables, and progress indicators
• Comprehensive error handling with actionable troubleshooting guidance
• Runtime validation using Zod schemas for type safety
• Modern TypeScript implementation with strict mode and full test coverage

Installation

npm install -g @steipete/inngest

Setup

Set your Inngest signing key as an environment variable:

export INNGEST_SIGNING_KEY="your-signing-key-here"

Get your signing key from: https://app.inngest.com/env/production/manage/signing-key

Environment Configuration

The CLI supports both production and development environments:

Production (Default)

# Uses https://api.inngest.com
inngest list --status Failed

Development Environment

# Uses local dev server at http://localhost:8288
inngest list --env dev --status Failed

# Custom dev server port
inngest list --env dev --dev-port 8080 --status Failed

# Branch/Preview environment (requires slug)
INNGEST_SIGNING_KEY=signkey-branch-... inngest list --env-slug branch/my-feature --status Failed

Environment Variables

• INNGEST_SIGNING_KEY - Your Inngest signing key (required)
• INNGEST_API_URL - Custom production API URL (optional)
• INNGEST_DEV_SERVER_URL - Custom dev server URL (optional)
• INNGEST_DEV_SERVER_PORT - Default dev server port (optional)
• INNGEST_ENV - Environment slug (e.g. production, branch/my-feature). Useful for branch environments.

Global Options

• --env <environment> - Switch between prod (default) and dev
• --dev-port <port> - Override dev server port (default: 8288)
• --env-slug <slug> - Override the environment slug sent to Inngest (same as INNGEST_ENV)
• -V, --version - Display version number

Usage

Output Formats

All commands support both table (default) and JSON output formats for easy integration with other tools:

# Default table format
inngest list --status Failed

# JSON format for programmatic use
inngest list --status Failed --format json

# Pipe JSON output to jq for processing
inngest list --status Failed --format json | jq '.runs[].run_id'

# Get specific fields from JSON
inngest status --run 01K4ZAM6W753HAT --format json | jq '.status'

Check Run Status

# Get status for a specific run (full ID)
inngest status --run 01K4ZAM6W753HATTAQ53E8YJ2T

# Get status using partial ID from table (12+ characters)
inngest status --run HATTAQ53E8YJ2T

# Get status for all runs of an event
inngest status --event 01HWAVEB858VPPX47Z65GR6P6R

# JSON output for integration
inngest status --run 01K4ZAM6W753HAT --format json
inngest status --event 01HWAVEB858VPP --format json | jq '.runs'

List Runs with Filtering

The CLI displays actual function names (e.g., sweetistics-system.jobs.sweeper) instead of UUIDs in the runs table for better readability.

# List all runs (default limit: 20) - shows function names
inngest list

# Filter by status
inngest list --status Running
inngest list --status Failed

# Filter by function name (supports partial matching)
inngest list --function-name "sweeper"
inngest list --function-name "embeddings/reconcile"
inngest list --function-name "system.jobs"

# Filter by function ID or name using --function (legacy option)
inngest list --function "process-payment"
inngest list --function "6cc723a1-30f3-4e16-bcaa-ae40619f9770"

# Time range filtering (status filters default to last 24 hours)
inngest list --status Failed                    # Last 24 hours
inngest list --status Failed --hours 48         # Last 48 hours  
inngest list --hours 6                          # Last 6 hours (any status)
inngest list --after "2024-01-01T00:00:00Z"     # Since specific time
inngest list --before "2024-01-01T23:59:59Z"    # Before specific time

# Combine filters
inngest list --status Running --function-name "send-email" --limit 50
inngest list --status Failed --function-name "embeddings" --hours 72

# Get all results (may take time)
inngest list --all

# Show full details instead of table format (includes input data and output)
inngest list --status Failed --details

# Get detailed view of last 10 failed runs with complete context
inngest list --status Failed --limit 10 --details --hours 72

# Show debug information during execution (performance monitoring)
inngest list --status Failed --details --verbose

# Paginate through results
inngest list --cursor "next-page-cursor"

# JSON format with pagination metadata
inngest list --status Failed --format json | jq '.has_more, .next_cursor'

# Process JSON output with external tools
inngest list --format json | jq '[.runs[] | {id: .run_id, status, function: .function_name}]'

Watch Runs in Real-time

# Watch a specific run (updates every 5 seconds)
inngest watch --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q

# Watch all runs for an event
inngest watch --event 01HWAVEB858VPPX47Z65GR6P6R

# Custom polling interval (in seconds)
inngest watch --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q --interval 10

# Set timeout (in minutes)
inngest watch --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q --timeout 30

Cancel Runs

# Cancel a specific run (with confirmation)
inngest cancel --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q

# Cancel without confirmation
inngest cancel --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q --yes

# Bulk cancel by function (requires app-id)
inngest cancel --app-id "my-app" --function "send-email" --yes

# Bulk cancel with time range
inngest cancel --app-id "my-app" --function "process-order" \
  --after "2024-01-01T00:00:00Z" \
  --before "2024-01-02T00:00:00Z" --yes

# Conditional cancellation with CEL expression
inngest cancel --app-id "my-app" --function "notify-user" \
  --if 'event.data.userId == "user_123"' --yes

# Dry run (preview what would be cancelled)
inngest cancel --app-id "my-app" --function "send-email" --dry-run

# JSON output for cancel operations
inngest cancel --run 01HWAVJ8ASQ5 --yes --format json
inngest cancel --app-id "my-app" --function "send-email" --dry-run --format json

View Job Details

# Get detailed job information for a run (full ID)
inngest jobs 01K4ZAM6W753HATTAQ53E8YJ2T

# Get job details using partial ID from table
inngest jobs HATTAQ53E8YJ2T

# JSON format for structured job data
inngest jobs 01K4ZAM6W753HAT --format json | jq '.jobs[] | {id, step, status}'

Check Cancellation Status

# Check the status of a bulk cancellation
inngest cancellation-status 01HWAVJ8ASQ5C3FXV32JS9DV9Q

# JSON format for monitoring cancellation progress
inngest cancellation-status 01HWAVJ8ASQ5 --format json | jq '.cancelled_count'

Debug and Performance Monitoring

Verbose Output

Use the --verbose or -v flag to see detailed debug information during command execution:

# See performance metrics and API call details
inngest list --status Failed --details --verbose

# Monitor search progress through time chunks
inngest list --status Failed --hours 168 --verbose

Debug information includes:

• API response metadata and timing
• Parallel chunk processing progress
• Pagination and search optimization details
• Event filtering and early termination stats

Performance Features

The CLI includes several performance optimizations:

• Parallel API requests: Up to 6 concurrent time-based chunks
• Early termination: Stops fetching when enough results found
• Smart result limiting: Requests optimal amount for filtering
• Efficient pagination: Uses cursors when available

Available Statuses

• Running - Job is currently executing
• Completed - Job finished successfully
• Failed - Job failed with an error
• Cancelled - Job was cancelled

Function Name Filtering

The CLI automatically extracts and displays readable function names from Inngest events instead of showing UUIDs. This makes it much easier to identify and filter runs.

Function Name Format: Function names typically follow patterns like:

• sweetistics-system.jobs.sweeper
• my-app.embeddings.reconcile
• user-service.notifications.send

Filtering Options:

• --function-name: Filter by function name with partial matching (recommended)
• --function: Filter by function ID (UUID) or function name (legacy support)

Time Range Filtering

Control which time period to search for runs. This is especially important when looking for failed runs or specific incidents.

Default Behavior:

• When filtering by status (e.g., --status Failed): searches last 24 hours
• Without status filtering: searches recent events only

Time Range Options:

• --hours N: Look back N hours from now
• --after TIMESTAMP: Show runs after specific time (ISO 8601 format)
• --before TIMESTAMP: Show runs before specific time (ISO 8601 format)

Examples:

# Find failed runs in last 24 hours (default when using --status)
inngest list --status Failed

# Search last 3 days for any cancelled runs
inngest list --status Cancelled --hours 72

# Look for runs since yesterday morning  
inngest list --after "2024-01-01T09:00:00Z"

# Find runs in a specific time window
inngest list --after "2024-01-01T09:00:00Z" --before "2024-01-01T17:00:00Z"

Environment Variables

• INNGEST_SIGNING_KEY - Your Inngest signing key (required)
• INNGEST_API_URL - Custom API URL (optional, defaults to https://api.inngest.com)

Examples

Monitor Function-Specific Jobs

# Monitor specific functions by name
inngest list --function-name "sweeper"
inngest list --function-name "embeddings/reconcile"

# Monitor failed jobs for specific functions
inngest list --status Failed --function-name "system.jobs"
inngest list --status Failed --function-name "embeddings"

# Watch for new failures in a specific function
inngest watch --event <EVENT_ID> --interval 30

Monitor Failed Jobs

# List failed runs from last 24 hours (default)
inngest list --status Failed

# Find failed runs from last week for incident analysis
inngest list --status Failed --hours 168

# Check for failed runs in specific function during incident window
inngest list --status Failed --function-name "payment-processor" \
  --after "2024-01-15T14:00:00Z" --before "2024-01-15T16:00:00Z"

# List failed runs with readable function names
# (shows: sweetistics-system.jobs.sweeper instead of UUID)
inngest list --status Failed --limit 10

# Get detailed view of failed runs with input data and error information
inngest list --status Failed --details

# Analyze specific failed runs with full context (input + output)
inngest list --status Failed --function-name "payment-processor" --details --limit 5

Bulk Cleanup

# Preview what would be cancelled
inngest cancel --app-id "my-app" --function "cleanup-task" --dry-run

# Cancel all runs for a function from yesterday
inngest cancel --app-id "my-app" --function "cleanup-task" \
  --after "2024-01-01T00:00:00Z" \
  --before "2024-01-02T00:00:00Z" --yes

Debug a Specific Run

# Get run details
inngest status --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q

# Get step-by-step job execution
inngest jobs 01HWAVJ8ASQ5C3FXV32JS9DV9Q

# Watch it live (if still running)
inngest watch --run 01HWAVJ8ASQ5C3FXV32JS9DV9Q

Example Output

The CLI shows readable function names in a formatted table:

$ inngest list --limit 3
ℹ Fetching runs...
┌──────────────┬─────────────┬─────────────────────────────────┬───────────────────────┬──────────┐
│ Run ID       │ Status      │ Function                        │ Started               │ Duration │
├──────────────┼─────────────┼─────────────────────────────────┼───────────────────────┼──────────┤
│ SG8GPCA7CATH │ ● Completed │ sweetistics-system.jobs.sweeper │ 9/12/2025, 5:25:00 PM │ 8.0s     │
├──────────────┼─────────────┼─────────────────────────────────┼───────────────────────┼──────────┤
│ 7N49HSG37BFW │ ● Completed │ sweetistics-system.jobs.sweeper │ 9/12/2025, 5:20:00 PM │ 12.3s    │
├──────────────┼─────────────┼─────────────────────────────────┼───────────────────────┼──────────┤
│ 4R0ET7SWCA4Z │ ● Cancelled │ sweetistics-system.jobs.sweeper │ 9/12/2025, 5:05:00 PM │ 13.3m    │
└──────────────┴─────────────┴─────────────────────────────────┴───────────────────────┴──────────┘
ℹ Total: 3 run(s)

Testing

The CLI includes comprehensive validation and error handling. You can test the CLI functionality:

# Run the included test script
node test-cli.js

# Test specific commands
inngest --help
inngest --version
inngest status --run <valid-run-id>

API Testing

When testing with real API endpoints, ensure:

1. Valid Signing Key: Your INNGEST_SIGNING_KEY has appropriate permissions
2. Correct API Version: The current implementation uses /v1/ endpoints
3. Network Access: Ensure connectivity to https://api.inngest.com

If you encounter 404 errors, the API endpoint structure might be different than expected. Check the latest API documentation for the correct endpoint paths.

API Reference

This CLI is designed to work with the official Inngest REST API:

• Get Run Status
• List Runs
• Cancel Run
• Get Jobs
• Bulk Cancel

Technical Documentation

See docs/spec.md for comprehensive technical specifications, including:

• Architecture overview
• API integration details
• Data models and validation
• Error handling strategies
• Performance considerations

License

MIT © Peter Steinberger