@hookstream/cli 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,262 @@
+# @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