CLI Reference

The Hook0 CLI is a command-line client for your Hook0 account. It lets you send events, manage subscriptions, receive webhooks locally for development, and automate your workflow — everything you can do in the Hook0 dashboard, from your terminal.

Key concepts

Term	Meaning
Event	Something that happened in your system (e.g., `user.account.created`)
Subscription	A rule: "when this event type occurs, deliver it to this URL"
Application	Your project or environment in Hook0

Learn more in the Concepts section.

Capabilities

Capability	Description
Local development	Receive webhooks on your machine via WebSocket tunnel — like ngrok, built into the CLI
Interactive testing	Compose and send test webhooks through a Terminal User Interface (TUI) with a built-in echo server (a local HTTP server that receives and displays webhook requests)
Event management	Send events, list history, inspect delivery attempts
Subscriptions	Full CRUD and enable/disable on subscriptions, with custom headers and labels
Event types	Full CRUD on event types using dotted convention (`service.resource.verb`)
Replay	Replay failed events individually or in bulk, with `--dry-run` preview and filters
Multi-profile	Named profiles per environment, credentials stored in the OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
Applications	List, inspect, and switch applications across organizations
Scriptable output	`--output json` (machine-readable), `--output table` (formatted columns), `--output compact` (one line per item, for grep/awk)
Shell completion	Bash, Zsh, Fish, PowerShell, Elvish

Installation

Requires Rust (Cargo).

cargo install --git https://gitlab.com/hook0/hook0.git hook0-cli

Verify:

hook0 --version

Try It Now

No Hook0 account needed for this demo — it uses the public relay server and a built-in echo server, bypassing the Hook0 API entirely. Run this single command:

hook0 example

This opens a TUI where you pick an event type, edit the JSON payload, and send it. A built-in echo server receives the webhook and displays the full request (headers, body, status) — all in one terminal, no configuration needed.

Quick Start

Before starting, create an account on app.hook0.com and go to your application dashboard to get your Application ID and Secret.

# 1. Set up your profile (prompts for API URL, application ID, and secret)
hook0 init

# 2. Start the local tunnel — gives you a public URL (printed in the terminal)
hook0 listen 3000

# 3. In another terminal, create a subscription pointing to that URL
hook0 subscription create \
  --url <RELAY_URL_FROM_STEP_2> \
  --events user.account.created \
  --label tenant=acme

# 4. Send an event — Hook0 delivers it to the subscription, which forwards to localhost:3000
hook0 event send user.account.created \
  --label tenant=acme \
  --payload '{"user_id": "usr_123"}'

Here is the full flow:

+--------------------+         +------------------------+
| hook0 listen 3000  |         | hook0 event send ...   |
+--------+-----------+         +----------+-------------+
         |                                |
         | 1. connects via                | 4. sends event
         |    WebSocket                   |    via HTTP
         |                                |
         v                                v
+--------+-----------+         +-----------+------------+
| Relay Server       |         | Hook0 API              |
| play.hook0.com     |<--------+ app.hook0.com/api/v1   |
+--------+-----------+         +------------------------+
         |                       5. API delivers to
         |                          subscription URL
         |                          (= relay URL from step 2)
         |
         | 6. relay forwards
         |    via WebSocket
         v
+--------+-----------+
| localhost:3000     |
| (your server)      |
+--------------------+

Step by step:

hook0 listen connects to the relay server and receives a public URL (e.g., https://play.hook0.com/in/<token>)
You create a subscription with that URL as the target (step 3 in the code above)
hook0 event send sends an event to the Hook0 API
The API delivers the event to all matching subscriptions, including the relay URL
The relay forwards the HTTP request through the WebSocket tunnel to your local machine

Usage Examples

Local Development

hook0 listen creates a secure WebSocket tunnel through the Hook0 relay server (play.hook0.com by default) — similar to tools like ngrok or localtunnel, but built into the CLI. It lets you receive webhooks on your local machine behind a firewall without exposing any ports.

# Forward webhooks to port 3000 (auto-detects if a server is running)
hook0 listen 3000

# Your local server handles webhooks on a specific path
hook0 listen http://localhost:8080/api/webhooks

# Keep the same public URL across restarts (token determines the URL)
hook0 listen 3000 --token my-stable-token

# Plain log output instead of the TUI dashboard (useful in CI or scripts)
hook0 listen 3000 --no-tui

Self-hosted Hook0: if you run your own Hook0 instance with its own relay server, point --relay-url to it. Use --insecure if the relay uses a self-signed TLS certificate.

hook0 listen 3000 --relay-url wss://relay.internal.example.com/ws --insecure

Forwarding to a remote target: by default, listen only forwards to localhost to prevent SSRF. To forward to an external URL (e.g., a shared staging server), opt in explicitly:

hook0 listen https://staging.example.com/webhooks --allow-external

Interactive Testing

hook0 example is a standalone demo that runs entirely in your terminal. It starts a built-in echo server, connects to the relay, and opens a TUI where you compose events, send them, and see the full delivery round-trip (request headers, payload, response status).

# Self-contained demo with built-in echo server
hook0 example

# Send example webhooks to your own local server instead of the echo server
hook0 example --target http://localhost:3000/webhooks

Sending Events

# Send an event with inline JSON payload
hook0 event send user.account.created \
  --label tenant=acme \
  --payload '{"user_id": "usr_123", "email": "[email protected]"}'

# Send from a file (useful for large payloads)
hook0 event send order.completed \
  --label tenant=acme \
  --payload-file ./payloads/order-completed.json

# Send with a custom event ID (idempotency)
hook0 event send invoice.paid \
  --label tenant=acme \
  --payload '{"invoice_id": "inv_456"}' \
  --event-id 550e8400-e29b-41d4-a716-446655440000

# Send a plain text payload
hook0 event send user.account.updated \
  --label tenant=acme \
  --payload 'user 123 updated their profile' \
  --content-type text/plain

Listing and Inspecting Events

# List the 100 most recent events
hook0 event list

# Get full details of a specific event
hook0 event get 550e8400-e29b-41d4-a716-446655440000

# Show delivery attempts for a specific event
hook0 event get 550e8400-e29b-41d4-a716-446655440000 --attempts

# Export as JSON for scripting
hook0 event list --output json | jq '.[].event_id'

Managing Event Types

# Create an event type using the dotted convention
hook0 event-type create user.account.created

# Create using individual components
hook0 event-type create --service order --resource payment --verb completed

# List all event types
hook0 event-type list

# Filter by service
hook0 event-type list --service user

# Delete an event type (with confirmation skip)
hook0 event-type delete user.account.deleted --yes

Managing Subscriptions

# Create a basic subscription
hook0 subscription create \
  --url https://api.example.com/webhooks \
  --events user.account.created,order.completed \
  --label tenant=acme

# Create with custom headers and description
hook0 subscription create \
  --url https://api.example.com/webhooks \
  --events order.completed \
  --label tenant=acme \
  --header Authorization="Bearer sk_live_xxx" \
  --header X-Custom="my-value" \
  --description "Production order webhook for Acme Corp"

# Create a disabled subscription (activate later)
hook0 subscription create \
  --url https://staging.example.com/webhooks \
  --events user.account.created \
  --label tenant=acme \
  --disabled

# List only enabled subscriptions
hook0 subscription list --enabled

# Update a subscription's endpoint and event types
hook0 subscription update <SUBSCRIPTION_ID> \
  --url https://new-endpoint.example.com/webhooks \
  --events user.account.created,user.account.updated

# Enable / disable
hook0 subscription enable <SUBSCRIPTION_ID>
hook0 subscription disable <SUBSCRIPTION_ID>

# Delete with confirmation skip
hook0 subscription delete <SUBSCRIPTION_ID> --yes

Replaying Failed Events

# Replay a single event by ID
hook0 replay 550e8400-e29b-41d4-a716-446655440000

# Preview what would be replayed (dry run)
hook0 replay --all --status failed --since 24h --dry-run

# Replay all failed events from the last 24 hours
hook0 replay --all --status failed --since 24h --confirm

# Replay failed events of a specific type with a batch limit
hook0 replay --all \
  --status failed \
  --event-type order.completed \
  --since 7d \
  --limit 50 \
  --confirm

# Replay events in a specific time window
hook0 replay --all --since 48h --until 24h --confirm

Managing Applications

# List all applications in your organization (requires a service token, not an application secret)
hook0 application list

# List applications in a specific organization (requires a service token)
hook0 application list --organization-id <ORG_ID>

# Show current application details
hook0 application current

# Get details of a specific application
hook0 application get <APPLICATION_ID>

# Switch active application for the current profile
hook0 application switch <APPLICATION_ID>

Multi-Profile Configuration

# Interactive setup wizard
hook0 init

# Non-interactive setup with a pre-configured event type
hook0 init --non-interactive --event-type user.account.created

# Login to a different environment
hook0 login --api-url https://staging.hook0.com/api/v1 --profile-name staging

# List all configured profiles
hook0 config list

# Show current configuration
hook0 config show

# Switch default profile
hook0 config set-default staging

# Run a single command against a different profile
hook0 event list --profile staging

# Remove a profile
hook0 config remove old-profile --yes

# Show config file location
hook0 config path

# Logout from current profile
hook0 logout

# Logout from all profiles
hook0 logout --all

Scripting and Automation

# Use environment variables instead of profiles (CI/CD friendly)
export HOOK0_API_URL=https://app.hook0.com/api/v1
export HOOK0_SECRET=your-secret
export HOOK0_APPLICATION_ID=your-app-id
hook0 event send deploy.completed --label env=production --payload '{"version": "1.2.3"}'

# Override per-command without env vars
hook0 event list \
  --api-url https://staging.hook0.com/api/v1 \
  --secret staging-secret \
  --application-id staging-app-id \
  --output json

# Pipe JSON output into jq
hook0 subscription list --output json | jq '.[] | select(.enabled == true) | .url'

# Count events
hook0 event list --output json | jq length

# Increase verbosity for debugging (-v info, -vv debug, -vvv trace)
hook0 event send user.test --label tenant=debug --payload '{}' -vv

Shell Completion

Generate shell completion scripts.

# Bash
eval "$(hook0 completion bash)"
# or save: hook0 completion bash > ~/.local/share/bash-completion/completions/hook0

# Zsh
eval "$(hook0 completion zsh)"
# or save: hook0 completion zsh > ~/.zfunc/_hook0

# Fish
hook0 completion fish > ~/.config/fish/completions/hook0.fish

# PowerShell
hook0 completion powershell | Out-String | Invoke-Expression

# Elvish
eval (hook0 completion elvish | slurp)

Environment Variables

Variable	Description	Used by
`HOOK0_PROFILE`	Default profile name	All commands
`HOOK0_API_URL`	API base URL	All authenticated commands
`HOOK0_SECRET`	Application secret	All authenticated commands
`HOOK0_APPLICATION_ID`	Application ID	All authenticated commands
`HOOK0_RELAY_URL`	WebSocket relay server URL	`listen`

Global Options

These options apply to all commands.

Option	Env Variable	Description	Default
`--profile <NAME>`	`HOOK0_PROFILE`	Profile to use	Default profile
`--output <FORMAT>`	—	Output format: `json`, `table`, `compact`	`table`
`--api-url <URL>`	`HOOK0_API_URL`	Override API URL	From profile
`--secret <SECRET>`	`HOOK0_SECRET`	Override application secret	From keyring
`--application-id <UUID>`	`HOOK0_APPLICATION_ID`	Override application ID	From profile
`--verbose`	—	Verbosity level (`-v`, `-vv`, `-vvv`)	`warn`

Command Reference

`hook0 init`

Set up your first profile

Usage: hook0 init [OPTIONS]

Options:

--non-interactive — Skip interactive prompts and use defaults
--event-type <EVENT_TYPE> — Event type to create

`hook0 login`

Authenticate with an Application Secret

Usage: hook0 login [OPTIONS]

Options:

--secret <SECRET> — Application Secret (UUID token)
--api-url <API_URL> — API URL

Default value: https://app.hook0.com/api/v1
-n, --profile-name <PROFILE_NAME> — Profile name to save credentials

Default value: default
--application-id <APPLICATION_ID> — Application ID (required - the Application Secret is tied to this application)

`hook0 logout`

Remove stored credentials

Usage: hook0 logout [OPTIONS]

Options:

-n, --profile-name <PROFILE_NAME> — Profile name to remove credentials for
--all — Remove all stored credentials

`hook0 whoami`

Display current application and profile

Usage: hook0 whoami

`hook0 listen`

Receive webhooks locally via tunnel

Usage: hook0 listen [OPTIONS] [TARGET]

Arguments:

<TARGET> — Local URL or port to forward webhooks to (auto-detects if not specified) Examples: 3000, http://localhost:3000/webhooks

Options:

--relay-url <RELAY_URL> — Hooks relay server URL (WebSocket endpoint)

Default value: wss://play.hook0.com/ws
--token <TOKEN> — Token to use (if not provided, a new one will be generated)
--ping-interval <PING_INTERVAL> — Ping interval in seconds

Default value: 30
--insecure — Disable TLS certificate verification (for self-signed certs)
--allow-external — Allow forwarding to non-localhost targets (external URLs)
--no-tui — Disable full-screen TUI mode (use plain log output instead)

`hook0 example`

Send a sample webhook to test your setup

Usage: hook0 example [OPTIONS]

Options:

--target <TARGET> — Target URL to forward webhooks to (default: built-in echo server)
--relay-url <RELAY_URL> — Relay server WebSocket URL

Default value: wss://play.hook0.com/ws
--token <TOKEN> — Token for the webhook URL (auto-generated if not specified)
--ping-interval <PING_INTERVAL> — Ping interval in seconds

Default value: 30
--insecure — Allow insecure TLS connections

`hook0 event`

Manage webhook events

Usage: hook0 event <COMMAND>

Subcommands:

send — Send a new event
list — List events
get — Get event details

`hook0 event send`

Send a new event

Usage: hook0 event send [OPTIONS] --label <LABEL> <EVENT_TYPE>

Arguments:

<EVENT_TYPE> — Event type (e.g., user.account.created)

Options:

-d, --payload <PAYLOAD> — JSON payload
-f, --payload-file <PAYLOAD_FILE> — Read payload from file
-l, --label <LABEL> — Labels in key=value format (required, can be repeated)
--event-id <EVENT_ID> — Custom event ID (UUID, auto-generated if not provided)
--content-type <CONTENT_TYPE> — Content type (default: application/json)

Default value: application/json

`hook0 event list`

List events

Usage: hook0 event list

`hook0 event get`

Get event details

Usage: hook0 event get [OPTIONS] <EVENT_ID>

Arguments:

<EVENT_ID> — Event ID

Options:

--attempts — Show request attempts for this event

`hook0 event-type`

Manage event types

Usage: hook0 event-type <COMMAND>

Subcommands:

create — Create a new event type
list — List event types
delete — Delete an event type

`hook0 event-type create`

Create a new event type

Usage: hook0 event-type create [OPTIONS] [NAME]

Arguments:

<NAME> — Event type name (e.g., user.account.created) or individual components

Options:

-s, --service <SERVICE> — Service name (alternative to full name)
-r, --resource <RESOURCE> — Resource type name (alternative to full name)
-b, --verb <VERB> — Verb name (alternative to full name)

`hook0 event-type list`

List event types

Usage: hook0 event-type list [OPTIONS]

Options:

--service <SERVICE> — Filter by service name

`hook0 event-type delete`

Delete an event type

Usage: hook0 event-type delete [OPTIONS] <NAME>

Arguments:

<NAME> — Event type name (e.g., user.account.created)

Options:

-y, --yes — Skip confirmation prompt

`hook0 subscription`

Manage subscriptions

Usage: hook0 subscription <COMMAND>

Subcommands:

create — Create a new subscription
list — List subscriptions
get — Get subscription details
update — Update a subscription
delete — Delete a subscription
enable — Enable a subscription
disable — Disable a subscription

`hook0 subscription create`

Create a new subscription

Usage: hook0 subscription create [OPTIONS] --url <URL> --events <EVENTS> --label <LABEL>

Options:

-u, --url <URL> — Webhook endpoint URL
-e, --events <EVENTS> — Event types to subscribe to (required, comma-separated or repeated)
-l, --label <LABEL> — Labels in key=value format (required, can be repeated)
--method <METHOD> — HTTP method (default: POST)

Default value: POST
-H, --header <HEADER> — Custom headers in key=value format (can be repeated)
-d, --description <DESCRIPTION> — Description
--disabled — Create disabled

`hook0 subscription list`

List subscriptions

Usage: hook0 subscription list [OPTIONS]

Options:

--enabled — Show only enabled subscriptions
--disabled — Show only disabled subscriptions

`hook0 subscription get`

Get subscription details

Usage: hook0 subscription get <SUBSCRIPTION_ID>

Arguments:

<SUBSCRIPTION_ID> — Subscription ID

`hook0 subscription update`

Update a subscription

Usage: hook0 subscription update [OPTIONS] <SUBSCRIPTION_ID>

Arguments:

<SUBSCRIPTION_ID> — Subscription ID

Options:

-u, --url <URL> — Webhook endpoint URL
-e, --events <EVENTS> — Event types to subscribe to (replaces existing)
-l, --label <LABEL> — Labels in key=value format (replaces existing)
--method <METHOD> — HTTP method
-H, --header <HEADER> — Custom headers (replaces existing)
-d, --description <DESCRIPTION> — Description
--enable — Enable the subscription
--disable — Disable the subscription

`hook0 subscription delete`

Delete a subscription

Usage: hook0 subscription delete [OPTIONS] <SUBSCRIPTION_ID>

Arguments:

<SUBSCRIPTION_ID> — Subscription ID

Options:

-y, --yes — Skip confirmation prompt

`hook0 subscription enable`

Enable a subscription

Usage: hook0 subscription enable <SUBSCRIPTION_ID>

Arguments:

<SUBSCRIPTION_ID> — Subscription ID

`hook0 subscription disable`

Disable a subscription

Usage: hook0 subscription disable <SUBSCRIPTION_ID>

Arguments:

<SUBSCRIPTION_ID> — Subscription ID

`hook0 application`

Manage applications

Usage: hook0 application <COMMAND>

Subcommands:

list — List applications
get — Get application details
switch — Switch to a different application
current — Show current application

`hook0 application list`

List applications

Usage: hook0 application list [OPTIONS]

Options:

--organization-id <ORGANIZATION_ID> — Organization ID (uses default if not specified)

`hook0 application get`

Get application details

Usage: hook0 application get [APPLICATION_ID]

Arguments:

<APPLICATION_ID> — Application ID (uses default if not specified)

`hook0 application switch`

Switch to a different application

Usage: hook0 application switch <APPLICATION_ID>

Arguments:

<APPLICATION_ID> — Application ID to switch to

`hook0 application current`

Show current application

Usage: hook0 application current

`hook0 replay`

Replay failed events

Usage: hook0 replay [OPTIONS] [EVENT_ID]

Arguments:

<EVENT_ID> — Event ID to replay

Options:

--all — Replay all events matching criteria (requires --confirm)
--status <STATUS> — Filter by status (failed, successful, etc.)
--since <SINCE> — Filter events since (e.g., 1h, 24h, 7d)
--until <UNTIL> — Filter events until (e.g., 1h, 24h, 7d)
--event-type <EVENT_TYPE> — Filter by event type
--dry-run — Dry run - show what would be replayed without actually replaying
--confirm — Confirm bulk replay operation
--limit <LIMIT> — Maximum number of events to replay

Default value: 100

`hook0 config`

Manage configuration and profiles

Usage: hook0 config <COMMAND>

Subcommands:

list — List all profiles
show — Show current configuration
set-default — Set default profile
remove — Remove a profile
path — Show configuration file path

`hook0 config list`

List all profiles

Usage: hook0 config list

`hook0 config show`

Show current configuration

Usage: hook0 config show

`hook0 config set-default`

Set default profile

Usage: hook0 config set-default <PROFILE>

Arguments:

<PROFILE> — Profile name to set as default

`hook0 config remove`

Remove a profile

Usage: hook0 config remove [OPTIONS] <PROFILE>

Arguments:

<PROFILE> — Profile name to remove

Options:

-y, --yes — Skip confirmation

`hook0 config path`

Show configuration file path

Usage: hook0 config path

`hook0 completion`

Generate shell completion scripts

Usage: hook0 completion <SHELL>

Arguments:

<SHELL> — Shell to generate completions for

Possible values: bash, elvish, fish, powershell, zsh

Key concepts​

Capabilities​

Installation​

Try It Now​

Quick Start​

Usage Examples​

Local Development​

Interactive Testing​

Sending Events​

Listing and Inspecting Events​

Managing Event Types​

Managing Subscriptions​

Replaying Failed Events​

Managing Applications​

Multi-Profile Configuration​

Scripting and Automation​

Shell Completion​

Environment Variables​

Global Options​

Command Reference​

hook0 init​

hook0 login​

hook0 logout​

hook0 whoami​

hook0 listen​

hook0 example​

hook0 event​

hook0 event send​

hook0 event list​

hook0 event get​

hook0 event-type​

hook0 event-type create​

hook0 event-type list​

hook0 event-type delete​

hook0 subscription​

hook0 subscription create​

hook0 subscription list​

hook0 subscription get​

hook0 subscription update​

hook0 subscription delete​

hook0 subscription enable​

hook0 subscription disable​

hook0 application​

hook0 application list​

hook0 application get​

hook0 application switch​

hook0 application current​

hook0 replay​

hook0 config​

hook0 config list​

hook0 config show​

hook0 config set-default​

hook0 config remove​

hook0 config path​

hook0 completion​

Key concepts

Capabilities

Installation

Try It Now

Quick Start

Usage Examples

Local Development

Interactive Testing

Sending Events

Listing and Inspecting Events

Managing Event Types

Managing Subscriptions

Replaying Failed Events

Managing Applications

Multi-Profile Configuration

Scripting and Automation

Shell Completion

Environment Variables

Global Options

Command Reference

`hook0 init`

`hook0 login`

`hook0 logout`

`hook0 whoami`

`hook0 listen`

`hook0 example`

`hook0 event`

`hook0 event send`

`hook0 event list`

`hook0 event get`

`hook0 event-type`

`hook0 event-type create`

`hook0 event-type list`

`hook0 event-type delete`

`hook0 subscription`

`hook0 subscription create`

`hook0 subscription list`

`hook0 subscription get`

`hook0 subscription update`

`hook0 subscription delete`

`hook0 subscription enable`

`hook0 subscription disable`

`hook0 application`

`hook0 application list`

`hook0 application get`

`hook0 application switch`

`hook0 application current`

`hook0 replay`

`hook0 config`

`hook0 config list`

`hook0 config show`

`hook0 config set-default`

`hook0 config remove`

`hook0 config path`

`hook0 completion`