@hookstream/cli

The command-line tool for hookstream — the modern event gateway for webhooks that just work.

Manage sources, destinations, connections, events, metrics, topics, alerts, and more — all from your terminal.

Install

npm install -g @hookstream/cli

Or run without installing:

npx @hookstream/cli sources list

Quick Start

# 1. Authenticate (opens browser)
hookstream login

# 2. Create a source to receive webhooks
hookstream sources create "Stripe Webhooks" --template stripe

# 3. Create a destination
hookstream destinations create "My API" --url https://api.example.com/webhooks

# 4. Connect source → destination
hookstream connections create "Stripe → API" --source <source-id> --destination <dest-id>

# 5. Stream webhooks in real-time
hookstream listen --forward http://localhost:3000/webhook

Authentication

# Browser-based login (recommended) — opens hookstream.io to create & approve key
hookstream login

# Manual entry
hookstream login -i

# Direct key
hookstream login --api-key hs_live_abc123...

# Environment variable (for CI/CD)
export HOOKSTREAM_API_KEY=hs_live_abc123...

# Per-command override
hookstream --api-key hs_live_... sources list

Precedence: --api-key flag > HOOKSTREAM_API_KEY env > config file (~/.config/hookstream/config.json)

Commands

Core

| Command | Description | |---------|-------------| | hookstream login | Authenticate via browser or API key | | hookstream logout | Remove stored credentials | | hookstream whoami | Show current auth context |

Sources

hookstream sources list                           # List all sources
hookstream sources create "My Source"              # Create a source
hookstream sources create "GitHub" --template github  # With provider template
hookstream sources get <id>                        # Get source details
hookstream sources delete <id>                     # Delete a source
hookstream sources templates                       # List provider templates

Destinations

hookstream destinations list                       # List destinations
hookstream destinations create "My API" --url https://...  # Create HTTP destination
hookstream destinations create "Queue" --type aws_sqs \
  --provider-config '{"queue_url":"...","region":"us-east-1"}'  # Non-HTTP
hookstream destinations get <id>                   # Get details
hookstream destinations circuit <id>               # Check circuit breaker
hookstream destinations circuit-reset <id>         # Reset circuit breaker
hookstream destinations delete <id>                # Delete

Connections

hookstream connections list                        # List connections
hookstream connections create "Pipeline" \
  --source <src-id> --destination <dest-id>        # Create connection
hookstream connections create "Filtered" \
  --source <src> --destination <dest> \
  --filter '[{"field":"body.type","operator":"eq","value":"payment.completed"}]'
hookstream connections get <id>                    # Get details
hookstream connections delete <id>                 # Delete

Events

hookstream events list                             # List recent events
hookstream events list --source <id> --limit 100   # Filter by source
hookstream events get <id>                         # Full event detail
hookstream events retry <id>                       # Retry all deliveries
hookstream events replay <id> --to https://...     # Replay to a URL

Deliveries

hookstream deliveries list                         # List delivery attempts
hookstream deliveries list --status failed          # Filter by status
hookstream deliveries get <id>                     # Get attempt details
hookstream deliveries retry <id>                   # Retry a delivery
hookstream deliveries dlq                          # View dead-letter queue

Topics (Pub/Sub)

hookstream topics list                             # List topics
hookstream topics create "Orders" --slug orders    # Create topic
hookstream topics subscribe <topic> <destination>  # Subscribe
hookstream topics publish orders --data '{"type":"order.created"}'  # Publish
hookstream topics unsubscribe <topic> <sub-id>     # Unsubscribe
hookstream topics delete <id>                      # Delete

Issues

hookstream issues list                             # List open issues
hookstream issues list --status all                # All statuses
hookstream issues get <id>                         # Issue details
hookstream issues update <id> --status resolved    # Update status
hookstream issues retry <id>                       # Retry failed deliveries

Alerts

hookstream alerts list                             # List alert rules
hookstream alerts create "High Failure" \
  --type failure_rate --channel <ch-id>            # Create rule
hookstream alerts get <id>                         # Rule details
hookstream alerts delete <id>                      # Delete

Notification Channels

hookstream channels list                           # List channels
hookstream channels create "Slack" \
  --type webhook --url https://hooks.slack.com/... # Create channel
hookstream channels get <id>                       # Channel details
hookstream channels test <id>                      # Send test notification
hookstream channels delete <id>                    # Delete

Collections (Instant Database)

hookstream collections list                        # List collections
hookstream collections get <id>                    # Collection details
hookstream collections stats <id>                  # Record count & schema
hookstream collections export <id>                 # Export as NDJSON
hookstream collections export <id> --format csv --output data.csv

Applications (Outbound Webhooks)

hookstream applications list                       # List applications
hookstream applications create "My App"            # Create application
hookstream applications get <id>                   # App details
hookstream applications delete <id>                # Delete

Metrics

hookstream metrics overview                        # Overview stats
hookstream metrics volume                          # Event volume (24h)
hookstream metrics volume --granularity day         # Daily breakdown

Billing

hookstream billing usage                           # Current usage & limits
hookstream billing subscription                    # Plan details

Testing & Debugging

# Send a test event to a source
hookstream test <source-id>
hookstream test <source-id> --payload '{"action":"test"}'
hookstream test <source-id> --file payload.json --method PUT

# Stream webhooks in real-time (creates ephemeral URL)
hookstream listen
hookstream listen --forward http://localhost:3000/webhook
hookstream listen --full  # Show full payloads

Global Flags

| Flag | Description | |------|-------------| | --api-key <key> | Override API key for this command | | --base-url <url> | Override API base URL | | --json | Machine-readable JSON output | | --help | Show help for any command | | --version | Show CLI version |

Global flags go before the subcommand:

hookstream --json sources list
hookstream --api-key hs_live_... events list

JSON Output

Every command supports --json for scripting:

# Pipe to jq
hookstream --json sources list | jq '.[].id'

# Use in shell scripts
SOURCE_ID=$(hookstream --json sources create "Automated" | jq -r '.id')

Configuration

Config file: ~/.config/hookstream/config.json (XDG compliant)

Environment variables:

• HOOKSTREAM_API_KEY — API key (overrides config file)
• HOOKSTREAM_BASE_URL — API base URL (default: https://hookstream.io)

Documentation

• CLI Overview
• Installation Guide
• Commands Reference
• Authentication

License

MIT