Skip to main content

CLI reference

The Hook0 CLI is a command-line client for your Hook0 account. Send events, manage subscriptions, receive webhooks locally, and automate your workflow. Everything you can do in the dashboard, from your terminal.

Key concepts​

TermMeaning
EventSomething that happened in your system (e.g., user.account.created)
SubscriptionA rule: "when this event type occurs, deliver it to this URL"
ApplicationYour project or environment in Hook0

Learn more in the Concepts section.

Capabilities​

CapabilityDescription
Local developmentReceive webhooks on your machine via WebSocket tunnel — like ngrok, built into the CLI
Interactive testingCompose 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 managementSend events, list history, inspect delivery attempts
SubscriptionsFull CRUD and enable/disable on subscriptions, with custom headers and labels
Event typesFull CRUD on event types using dotted convention (service.resource.verb)
ReplayReplay failed events individually or in bulk, with --dry-run preview and filters
Multi-profileNamed profiles per environment, credentials stored in the OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
ApplicationsList, 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 completionBash, 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. This uses the public relay server and a built-in echo server, bypassing the Hook0 API entirely:

hook0 example

This opens a TUI where you pick an event type, edit the JSON payload, and send it. The built-in echo server receives the webhook and shows the full request (headers, body, status) 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:

Step by step:

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

Usage examples​

Local development​

hook0 listen creates a WebSocket tunnel through the Hook0 relay server (play.hook0.com by default), similar to ngrok or localtunnel but built into the CLI. It lets you receive webhooks on your local machine behind a firewall without exposing 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​

VariableDescriptionUsed by
HOOK0_PROFILEDefault profile nameAll commands
HOOK0_API_URLAPI base URLAll authenticated commands
HOOK0_SECRETApplication secretAll authenticated commands
HOOK0_APPLICATION_IDApplication IDAll authenticated commands
HOOK0_RELAY_URLWebSocket relay server URLlisten

Global options​

These options apply to all commands.

OptionEnv VariableDescriptionDefault
--profile <NAME>HOOK0_PROFILEProfile to useDefault profile
--output <FORMAT>—Output format: json, table, compacttable
--api-url <URL>HOOK0_API_URLOverride API URLFrom profile
--secret <SECRET>HOOK0_SECRETOverride application secretFrom keyring
--application-id <UUID>HOOK0_APPLICATION_IDOverride application IDFrom 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:

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