npm package: @hookstream/cli
Description: hookstream CLI — manage webhooks from the terminal
Latest version: 0.2.1

# @hookstream/cli

The command-line tool for [hookstream](https://hookstream.io) — the modern event gateway for webhooks that just work.

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

## Install

```bash
npm install -g @hookstream/cli
```

Or run without installing:

```bash
npx @hookstream/cli sources list
```

## Quick Start

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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)

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

### Metrics

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

### Billing

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

### Testing & Debugging

```bash
# 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:

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

## JSON Output

Every command supports `--json` for scripting:

```bash
# 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](https://hookstream.io/docs/cli/overview)
- [Installation Guide](https://hookstream.io/docs/cli/installation)
- [Commands Reference](https://hookstream.io/docs/cli/commands)
- [Authentication](https://hookstream.io/docs/cli/authentication)

## License

MIT