CLI Command Reference

Global Flags

These flags are available on every hb command.

Flag	Default	Description
--json	false	Output machine-readable JSON on stdout
--no-color	false	Disable ANSI colour output

Colour Output

Colour is off by default. It only turns on when stdout is a terminal and none of the following disable it, checked in this order:

1. --json — always disables colour
2. --no-color — always disables colour
3. The NO_COLOR environment variable — disables colour when set to a non-empty value (an empty NO_COLOR counts as not set, per no-color.org)
4. Whether stdout is a terminal — colour is off when output is piped or redirected

JSON Output: Overview

With --json, JSON goes to stdout alone — one value per invocation, or one JSON object per line for streaming commands like hb listen. Human-readable text, warnings, and errors go to stderr instead. Output is never coloured under --json, regardless of the other colour flags.

hb login

Authenticate with your HookBridge API key.

hb login
hb login --api-key YOUR_API_KEY

The CLI prompts for your API key, verifies it against the HookBridge API, and saves credentials to the config file.

Flag	Description
--api-key	API key for non-interactive login

hb logout

Remove stored credentials.

hb logout

Deletes the config file. If you are already logged out, this prints a confirmation message without error.

hb listen

Listen for webhooks and forward them to a local server.

On startup, the CLI finds an existing CLI-mode inbound endpoint in your project or creates one automatically. It then prints the Webhook URL and connects to receive incoming webhooks.

Webhooks are forwarded to your local server as HTTP POST requests with the original headers, body, and content type preserved.

Examples

Forward webhooks to a local server on port 3000:

hb listen --port 3000

Forward to a specific URL path on your local server:

hb listen --forward http://localhost:8080/webhooks/stripe

Display webhooks in the terminal without forwarding, with full headers and body:

hb listen --no-forward --verbose

Flags

Flag	Short	Default	Description
--port	-p	3000	Localhost port to forward to (http://localhost:{port})
--forward			Full URL to forward to (overrides --port)
--no-forward		false	Display webhooks without forwarding
--verbose	-v	false	Show full headers and body for each webhook
--endpoint			Use a specific endpoint by ID instead of auto-selecting

Output

Each webhook prints a log line:

12:34:01  POST  →  200  89ms  application/json  (328 bytes)

Status codes are color-coded: green for 2xx, red for 4xx/5xx, yellow for connection errors — but only when colour is on. Colour is off unless stdout is a terminal, and --no-color, the NO_COLOR environment variable, or --json each disable it. See Colour Output above.

With --verbose, headers and body are printed below each log line.

JSON Output: listen

With --json, hb listen streams one JSON object per line (NDJSON) to stdout. A ready event is always first; a shutdown event is always last.

ready, printed once the listener is connected:

{"event":"ready","endpoint_id":"01a002bd-d4ce-710b-b817-a757e78d0a16","forward_to":"http://localhost:3000"}

forward_to is "" when --no-forward is used.

webhook, printed once per received webhook. Always includes event, id, content_type, size_bytes, received_at, and forwarded. What else is present depends on what happened to the webhook:

1. Forward succeeded — forwarded:true, plus status_code and latency_ms.
2. Forward failed — forwarded:false, plus error.
3. hb listen --no-forward — forwarded:false, with no error, status_code, or latency_ms at all.

forwarded:false alone does not tell you whether the forward failed or was never attempted — check for the error field directly rather than inferring it from forwarded.

Successful forward:

{"event":"webhook","id":"01a002bd-e297-7dae-bc8d-0f63ed59ce00","content_type":"application/json","size_bytes":56,"received_at":"2026-08-15T00:06:34.22206422Z","forwarded":true,"status_code":200,"latency_ms":3}

Failed forward:

{"event":"webhook","id":"01a002d3-a839-7c31-a61d-cf00f68890c7","content_type":"application/json","size_bytes":56,"received_at":"2026-08-15T00:30:21.050323773Z","forwarded":false,"error":"connection refused or timeout"}

The error string above is abbreviated for this reference — the actual message includes the underlying dial error.

--no-forward (no forward attempted):

{"event":"webhook","id":"01a002bd-e297-7dae-bc8d-0f63ed59ce00","content_type":"application/json","size_bytes":56,"received_at":"2026-08-15T00:06:34.22206422Z","forwarded":false}

shutdown, printed once when the listener stops:

{"event":"shutdown","received":1}

Diagnostics are also NDJSON, but printed to stderr rather than stdout: {"event":"status","message":"..."} and {"event":"error","message":"..."}.

A few behaviors worth knowing:

• --verbose has no effect under --json — headers and bodies are never included in webhook events, because payloads can carry secrets.
• The Webhook URL (receive URL) never appears anywhere in the listen JSON stream.

Graceful Shutdown

Press Ctrl+C to stop listening. The CLI prints a summary of how many webhooks were received during the session.

hb endpoints

List CLI-mode inbound endpoints in your project.

hb endpoints

Prints a table of CLI-mode endpoints with their ID, name, and active status.

ID                                       NAME                 ACTIVE
--------------------------------------   ------------------   ------
ie_abc123...                             CLI Endpoint         yes

If no CLI-mode endpoints exist, the command suggests creating one.

JSON Output: endpoints

With --json, hb endpoints prints a single JSON array on one line, with exactly three fields per element:

[{"id":"01a002bd-d4ce-710b-b817-a757e78d0a16","name":"CLI Endpoint","active":true}]

active is a JSON boolean, not the yes/no string the table prints. When there are no CLI-mode endpoints, the output is [] — never null and never zero bytes.

The Webhook URL (receive URL) is deliberately left out of this output, since it embeds a secret — this is intentional, not an oversight. The receive URL is only printed once, when the endpoint is created (see hb endpoints create below).

hb endpoints create

Create a new CLI-mode inbound endpoint.

hb endpoints create
hb endpoints create --name "Stripe Local"
hb endpoints create --ephemeral --ttl-minutes 30

Flag	Default	Description
--name	CLI Endpoint	Name for the new endpoint
--ephemeral	false	Create a short-lived endpoint that expires automatically
--ttl-minutes	0	Minutes until an ephemeral endpoint expires (1-1440)

Prints the endpoint ID and Webhook URL (receive URL) on success.

Validation

--ttl-minutes is checked locally before any request is sent to the HookBridge API — an invalid combination fails immediately with no HTTP request made:

• --ttl-minutes without --ephemeral: --ttl-minutes requires --ephemeral
• --ttl-minutes outside 1–1440, including an explicit 0: --ttl-minutes must be between 1 and 1440

JSON Output: endpoints create

With --json, hb endpoints create prints a single JSON object:

{"id":"01a002bd-d4ce-710b-b817-a757e78d0a16","receive_url":"https://receive.hookbridge.io/v1/webhooks/receive/01a002bd-d4ce-710b-b817-a757e78d0a16/7c73a1e0f4b28d6590ac4471e2b8d3c5"}

hb endpoints create is the only command that prints receive_url. The receive URL embeds a secret path component — treat it as a credential, not a bare identifier.

hb endpoints delete

Delete a CLI-mode inbound endpoint.

hb endpoints delete 01a002bd-d4ce-710b-b817-a757e78d0a16
hb endpoints delete 01a002bd-d4ce-710b-b817-a757e78d0a16 --force

Argument	Description
<id>	ID of the endpoint to delete (required)

Flag	Short	Default	Description
--force	-f	false	Skip the confirmation prompt

Confirmation Prompt

When stdin is a terminal, the command prompts before deleting:

Delete endpoint 01a002bd-d4ce-710b-b817-a757e78d0a16? This cannot be undone. [y/N]:

Only y or yes (case-insensitive) confirms the deletion. Anything else, including a bare Enter, aborts with an aborted error and a non-zero exit code.

When stdin is not a terminal — the usual case in CI — the prompt is skipped entirely and the delete proceeds. --force skips the prompt unconditionally, and is a good habit in scripts even when you expect a non-interactive shell.

Errors

Deleting an ID that doesn’t exist, or that was already deleted, exits non-zero with:

Error: inbound endpoint "01a002bd-d4ce-710b-b817-a757e78d0a16" not found — it may already be deleted

JSON Output: endpoints delete

With --json, a successful delete prints:

{"deleted":true,"id":"01a002bd-d4ce-710b-b817-a757e78d0a16"}

hb version

Print the installed CLI version.

hb version

Environment Variables

Variable	Description
HB_API_KEY	Override the stored API key
NO_COLOR	Disable ANSI colour output when set to a non-empty value

Environment variables take precedence over values in the config file.

Config File

Credentials are stored in a config.json file inside the .hookbridge directory under your home folder:

Platform	Path
macOS / Linux	~/.hookbridge/config.json
Windows	%USERPROFILE%\.hookbridge\config.json

{
  "api_key": "hb_live_...",
  "project_id": "proj_..."
}

On macOS and Linux, the file is created with 0600 permissions (owner read/write only).