Command Reference

Complete reference for all webhook CLI commands, options, and usage patterns.

Global Commands

`hookvm --help`

Display help information for the CLI tool.

hookvm --help
hookvm -h

Output:

Usage: hookvm [options] [command]

Webhook monitoring and management CLI tool

Options:
  -V, --version      display version number
  -h, --help         display help for command

Commands:
  listen <endpoint>  Monitor webhook events in real-time
  help [command]     display help for command

`hookvm --version`

Display the current version of the CLI tool.

hookvm --version
hookvm -V

Output:

hookVM CLI v1.0.0

Main Commands

`listen`

Monitor webhook events in real-time from a specified endpoint.

Syntax

hookvm listen <endpoint-url> [options]

Arguments

<endpoint-url> (required)

Your webhook endpoint URL to monitor
Must include the full URL with endpoint ID
Format: https://domain.com/hooks/endpoint-id

Options

-t, --target <url> Forward webhook events to a local development server.

hookvm listen endpoint-url --target http://localhost:3000/webhooks
hookvm listen endpoint-url -t http://localhost:3000/webhooks

--disable-ui Disable the interactive terminal UI and use simple console output.

hookvm listen endpoint-url --disable-ui

--header <header> Add custom headers to forwarded requests (can be used multiple times).

hookvm listen endpoint-url \
  --target http://localhost:3000/webhooks \
  --header "Authorization: Bearer token" \
  --header "X-Custom: value"

Examples

Basic monitoring:

hookvm listen https://hookvm.com/hooks/c2a996bf-4b85-43f9-a2f6-0dfa3a3b0326

Monitor with local forwarding:

hookvm listen https://hookvm.com/hooks/c2a996bf-4b85-43f9-a2f6-0dfa3a3b0326 \
  --target http://localhost:3000/webhooks

Console mode (no interactive UI):

hookvm listen https://hookvm.com/hooks/c2a996bf-4b85-43f9-a2f6-0dfa3a3b0326 \
  --disable-ui

With custom headers:

hookvm listen https://hookvm.com/hooks/c2a996bf-4b85-43f9-a2f6-0dfa3a3b0326 \
  --target http://localhost:3000/webhooks \
  --header "Authorization: Bearer dev-token-123" \
  --header "X-Environment: development"

Interactive UI Commands

When using the default interactive terminal UI, these keyboard shortcuts are available:

Key	Action
`↑` / `↓`	Navigate event list
`j` / `k`	Navigate event list (vi-style)
`Tab`	Switch between panels
`Enter`	View event details

Key	Action
`1`	Switch to Overview tab
`2`	Switch to Headers tab
`3`	Switch to Body tab
`4`	Switch to Query Parameters tab

Actions

Key	Action
`c`	Clear all events
`h`	Show/hide help panel
`q`	Quit application
`Ctrl+C`	Quit application
`Esc`	Close help panel

Mouse Support

Action	Result
Click event	Select event
Scroll	Navigate lists
Click tabs	Switch detail tabs

Environment Variables

`WEBHOOK_CLI_CONFIG`

Set custom configuration file path.

export WEBHOOK_CLI_CONFIG=/path/to/custom/config.json
hookvm listen endpoint-url

`WEBHOOK_CLI_LOG_LEVEL`

Set logging level for debugging.

export WEBHOOK_CLI_LOG_LEVEL=debug
hookvm listen endpoint-url

Levels: error, warn, info, debug

`NO_COLOR`

Disable colored output.

export NO_COLOR=1
hookvm listen endpoint-url

Configuration File

The CLI can use a configuration file for default settings:

Location

macOS/Linux: ~/.webhook-cli/config.json
Windows: %USERPROFILE%\.webhook-cli\config.json

Format

{
  "defaultTarget": "http://localhost:3000/webhooks",
  "headers": [
    "Authorization: Bearer default-token",
    "X-Environment: development"
  ],
  "ui": {
    "disabled": false,
    "theme": "dark"
  },
  "logging": {
    "level": "info",
    "file": "~/.webhook-cli/logs/webhook.log"
  }
}

Configuration Options

defaultTarget (string)

Default target URL for forwarding
Can be overridden with --target option

headers (array)

Default headers to add to forwarded requests
Format: ["Header-Name: value"]

ui.disabled (boolean)

Default UI mode (true = console mode)
Can be overridden with --disable-ui

ui.theme (string)

Color theme: "dark" or "light"

logging.level (string)

Default log level: "error", "warn", "info", "debug"

logging.file (string)

Log file path (optional)

Exit Codes

The CLI uses standard exit codes:

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid usage (wrong arguments)
`3`	Connection error
`4`	Authentication error
`5`	Network error

Error Messages

Common Error Formats

Invalid URL:

✗ Invalid endpoint URL format. Expected format: https://domain.com/hooks/endpoint-id

Example: webhook https://api.example.com/hooks/c2a996bf-4b85-43f9-a2f6-0dfa3a3b0326

Connection Failed:

✗ Unable to connect to webhook endpoint
Make sure the endpoint URL is correct and the service is running

Target URL Error:

✗ Invalid target URL format.
✗ Target URL must use HTTP or HTTPS protocol.

WebSocket Error:

✗ WebSocket connection failed: [error details]

Debugging

Verbose Output

Enable debug logging:

WEBHOOK_CLI_LOG_LEVEL=debug hookvm listen endpoint-url

Log Files

Enable file logging:

mkdir -p ~/.webhook-cli/logs
WEBHOOK_CLI_LOG_FILE=~/.webhook-cli/logs/debug.log \
  hookvm listen endpoint-url

Network Debugging

Test connectivity:

# Test endpoint reachability
curl -I https://hookvm.com/hooks/your-endpoint-id

# Test WebSocket connectivity  
wscat -c wss://hookvm.com/ws

# Test local target
curl -X POST http://localhost:3000/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Usage Patterns

Development Workflow

# Start your local server
npm run dev

# In another terminal, start webhook monitoring with forwarding
hookvm listen https://hookvm.com/hooks/your-endpoint-id \
  --target http://localhost:3000/webhooks

# Trigger webhooks from your service's dashboard or API
# Watch events flow through CLI to your local handler

Production Monitoring

# Monitor production endpoint without forwarding
hookvm listen https://hookvm.com/hooks/prod-endpoint-id \
  --disable-ui > webhook-monitor.log 2>&1 &

# Monitor in background with logging
nohup hookvm listen https://hookvm.com/hooks/prod-endpoint-id \
  --disable-ui >> /var/log/webhook-monitor.log 2>&1 &

Team Development

# Each developer monitors their own endpoint
hookvm listen https://hookvm.com/hooks/dev-alice-endpoint \
  --target http://localhost:3000/webhooks

hookvm listen https://hookvm.com/hooks/dev-bob-endpoint \
  --target http://localhost:3001/webhooks

Multiple Services

# Monitor multiple webhook sources
# Terminal 1 - Stripe
hookvm listen https://hookvm.com/hooks/stripe-endpoint \
  --target http://localhost:3000/webhooks/stripe

# Terminal 2 - GitHub  
hookvm listen https://hookvm.com/hooks/github-endpoint \
  --target http://localhost:3000/webhooks/github

# Terminal 3 - Custom API
hookvm listen https://hookvm.com/hooks/api-endpoint \
  --target http://localhost:3000/webhooks/api

Integration with Other Tools

Process Managers

PM2

# ecosystem.config.js
module.exports = {
  apps: [{
    name: 'webhook-monitor',
    script: 'webhook',
    args: 'listen https://hookvm.com/hooks/endpoint-id --disable-ui',
    env: {
      WEBHOOK_CLI_LOG_LEVEL: 'info'
    }
  }]
};

systemd

# /etc/systemd/system/webhook-monitor.service
[Unit]
Description=Webhook Monitor
After=network.target

[Service]
Type=simple
User=webhook
ExecStart=/usr/local/bin/hookvm listen https://hookvm.com/hooks/endpoint-id --disable-ui
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Docker

FROM node:18-alpine

RUN npm install -g @hookvm/cli

CMD ["webhook", "listen", "$ENDPOINT_URL", "--disable-ui", "--target", "$TARGET_URL"]

docker run -e ENDPOINT_URL=https://hookvm.com/hooks/endpoint-id \
           -e TARGET_URL=http://host.docker.internal:3000/webhooks \
           webhook-cli

Need more help? Check the troubleshooting guide or installation instructions.

Command Reference

Global Commands

`hookvm --help`

`hookvm --version`

Main Commands

`listen`

Syntax

Arguments

Options

Examples

Interactive UI Commands

Navigation

Tab Navigation

Actions

Mouse Support

Environment Variables

`WEBHOOK_CLI_CONFIG`

`WEBHOOK_CLI_LOG_LEVEL`

`NO_COLOR`

Configuration File

Location

Format

Configuration Options

Exit Codes

Error Messages

Common Error Formats

Debugging

Verbose Output

Log Files

Network Debugging

Usage Patterns

Development Workflow

Production Monitoring

Team Development

Multiple Services

Integration with Other Tools

Process Managers

PM2

systemd

Docker

Global Commands​

hookvm --help​

hookvm --version​

Main Commands​

listen​

Syntax​

Arguments​

Options​

Examples​

Interactive UI Commands​

Navigation​

Tab Navigation​

Actions​

Mouse Support​

Environment Variables​

WEBHOOK_CLI_CONFIG​

WEBHOOK_CLI_LOG_LEVEL​

NO_COLOR​

Configuration File​

Location​

Format​

Configuration Options​

Exit Codes​

Error Messages​

Common Error Formats​

Debugging​

Verbose Output​

Log Files​

Network Debugging​

Usage Patterns​

Development Workflow​

Production Monitoring​

Team Development​

Multiple Services​

Integration with Other Tools​

Process Managers​

PM2​

systemd​

Docker​

Global Commands

`hookvm --help`

`hookvm --version`

Main Commands

`listen`

Syntax

Arguments

Options

Examples

Interactive UI Commands

Navigation

Tab Navigation

Actions

Mouse Support

Environment Variables

`WEBHOOK_CLI_CONFIG`

`WEBHOOK_CLI_LOG_LEVEL`

`NO_COLOR`

Configuration File

Location

Format

Configuration Options

Exit Codes

Error Messages

Common Error Formats

Debugging

Verbose Output

Log Files

Network Debugging

Usage Patterns

Development Workflow

Production Monitoring

Team Development

Multiple Services

Integration with Other Tools

Process Managers

PM2

systemd

Docker