CLI Command Reference

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.

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

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.

hb endpoints create

Create a new CLI-mode inbound endpoint.

hb endpoints create
hb endpoints create --name "Stripe Local"

Flag	Default	Description
--name	CLI Endpoint	Name for the new endpoint

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

hb version

Print the installed CLI version.

hb version

Environment Variables

Variable	Description
HB_API_KEY	Override the stored API key

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).