docs: CLI README — add local try-it, JSON output example, command descriptions

- "Try it Locally (2 minutes)" section with copy-paste steps
- "Why hookflare?" one-liner differentiator vs SaaS alternatives
- --json output example for connect command (agent-friendly)
- Command table with one-line descriptions per command
- Note on init idempotency and forwarded headers

Author: linyiru

packages/cli/README.md

@@ -16,30 +16,53 @@ Stripe/GitHub/Slack → hookflare (Cloudflare edge) → your API
                       └─ never lose an event
 ```
 
-hookflare sits between webhook providers and your application. It accepts webhooks at 300+ Cloudflare edge locations, verifies signatures, and reliably delivers them to your API with automatic retries, circuit breaking, and a dead letter queue. Zero servers to manage.
+hookflare sits between webhook providers and your application. It accepts webhooks at 300+ Cloudflare edge locations, verifies signatures, and reliably delivers them to your API with automatic retries, circuit breaking, and a dead letter queue. Zero servers to manage, zero idle cost.
 
-## Quick Start
+**Why hookflare?** Unlike SaaS webhook tools (Hookdeck, Svix), hookflare runs on **your own** Cloudflare account — you own the data, pay Cloudflare directly ($0 on free tier for most workloads), and deploy in 30 seconds.
 
-### 1. Deploy hookflare
-
-If you haven't deployed hookflare yet, see the [deployment guide on GitHub](https://github.com/hookedge/hookflare#quick-start) — one-click deploy to Cloudflare or `npx wrangler deploy`.
-
-### 2. Install the CLI
+## Try it Locally (2 minutes)
 
 ```bash
+# 1. Clone and start
+git clone https://github.com/hookedge/hookflare.git && cd hookflare
+pnpm install && pnpm --filter @hookflare/shared build && pnpm --filter @hookflare/providers build
+pnpm --filter @hookflare/worker db:migrate:local
+pnpm --filter @hookflare/worker dev   # starts on http://localhost:8787
+
+# 2. In another terminal — install CLI and bootstrap
 npm i -g hookflare
+hookflare config set api_url http://localhost:8787
+hookflare init
+
+# 3. Create a Stripe webhook pipeline
+hookflare connect stripe --secret whsec_test --to https://httpbin.org/post
+
+# 4. Send a test webhook
+curl -X POST http://localhost:8787/webhooks/<source_id_from_output> \
+  -H "Content-Type: application/json" \
+  -d '{"type":"payment_intent.succeeded","data":{"amount":4999}}'
+
+# 5. Check delivery
+hookflare events ls
 ```
 
-### 3. Connect to your instance
+## Quick Start (Production)
+
+### 1. Deploy hookflare
+
+See the [deployment guide on GitHub](https://github.com/hookedge/hookflare#quick-start) — one-click deploy to Cloudflare or `npx wrangler deploy`.
+
+### 2. Install the CLI and bootstrap
 
 ```bash
+npm i -g hookflare
 hookflare config set api_url https://your-hookflare.workers.dev
 hookflare init    # creates your admin API key (stored automatically)
 ```
 
-`init` calls the one-time bootstrap endpoint to create your first API key. The key is saved to `~/.hookflare/config.json`. All subsequent commands authenticate with it.
+`init` calls the one-time bootstrap endpoint to create your first API key. The key is saved to `~/.hookflare/config.json`. All subsequent commands authenticate with it. Running `init` again on an already-bootstrapped instance is a no-op.
 
-### 4. Set up Stripe webhooks
+### 3. Set up Stripe webhooks
 
 ```bash
 hookflare connect stripe \
@@ -60,38 +83,60 @@ Webhook URL: https://your-hookflare.workers.dev/webhooks/src_a1b2c3
 Next: Add this URL to your Stripe Dashboard → Developers → Webhooks.
 ```
 
-Omit `--events` to forward all events.
+Omit `--events` to forward all events. hookflare forwards the original payload as-is to your destination with these headers added: `X-Hookflare-Event-Id`, `X-Hookflare-Delivery-Id`, `X-Hookflare-Attempt`.
 
 ## What You Can Do
 
 - **Connect providers** — Stripe, GitHub, Slack, Shopify, Vercel with one command
 - **Inspect & replay events** — view delivery attempts, replay failed events
-- **Monitor health** — circuit breaker status, DLQ inspection, real-time streaming
-- **Manage routing** — fan-out one source to multiple destinations with event filters
-- **Backup & migrate** — export/import configuration between instances
+- **Monitor health** — circuit breaker status, DLQ inspection, real-time streaming with `hookflare tail`
+- **Manage routing** — fan-out one source to multiple destinations with event type filters
+- **Backup & migrate** — export/import configuration, one-command instance-to-instance migration
 
 ## Agent-Friendly
 
-The CLI is built for AI agents. `--json` structured output, `--dry-run` safe validation, `--data` raw JSON input, and `hookflare schema` for runtime API discovery. See [AGENTS.md](https://github.com/hookedge/hookflare/blob/main/packages/cli/AGENTS.md) for the complete agent guide.
+The CLI is built for AI agents. See [AGENTS.md](https://github.com/hookedge/hookflare/blob/main/packages/cli/AGENTS.md) for the complete guide.
 
 ```bash
-hookflare schema sources                             # discover fields
-hookflare connect stripe --dry-run --json -d '{...}'  # validate
-hookflare connect stripe --json -d '{...}'            # execute
+# Discover → Validate → Execute
+hookflare schema sources                              # discover fields at runtime
+hookflare connect stripe --dry-run --json -d '{...}'   # validate without creating
+hookflare connect stripe --json -d '{...}'             # execute, get JSON output
 ```
 
-## All Commands
+`--json` output example:
+
+```json
+{
+  "data": {
+    "source": { "id": "src_a1b2c3", "name": "stripe", "provider": "stripe" },
+    "destination": { "id": "dst_d4e5f6", "url": "https://api.myapp.com/hooks" },
+    "subscription": { "id": "sub_g7h8i9", "event_types": ["payment_intent.*"] },
+    "webhook_url": "https://your-hookflare.workers.dev/webhooks/src_a1b2c3"
+  }
+}
+```
+
+Key flags: `--json` (structured output), `--dry-run` (safe validation), `-d/--data` (raw JSON input), `--fields` (limit output columns), `hookflare schema` (API introspection).
+
+## Commands
 
-| Category | Commands |
+| Command | Description |
 |---|---|
-| **Setup** | `connect`, `init`, `config`, `health` |
-| **Providers** | `providers ls`, `providers describe` |
-| **Resources** | `sources`, `dest`, `subs` (create/ls/rm) |
-| **Events** | `events ls/get/replay`, `tail` |
-| **Operations** | `export`, `import`, `migrate`, `dev` |
-| **Introspection** | `schema` |
-
-Run `hookflare --help` or `hookflare <command> --help` for details.
+| `connect <provider>` | One-shot setup: source + destination + subscription |
+| `init` | Bootstrap admin API key on a fresh instance |
+| `providers ls/describe` | Browse supported providers, events, and verification |
+| `sources create/ls/get/rm` | Manage webhook receiving endpoints |
+| `dest create/ls/get/rm` | Manage delivery destinations with retry policies |
+| `subs create/ls/rm` | Manage routing rules (source → destination) |
+| `events ls/get/replay` | Inspect received events and replay failed deliveries |
+| `tail` | Real-time event and delivery streaming |
+| `dev` | Local development tunnel with signature verification |
+| `export/import` | Backup and restore configuration |
+| `migrate` | Instance-to-instance migration |
+| `schema [resource]` | Runtime API schema introspection |
+| `config set/get` | CLI configuration (`api_url`, `token`) |
+| `health` | Check server connectivity and setup status |
 
 ## Links