Skip to main content

Complete CLI Reference

The hookVM CLI (hookvm) is a powerful command-line tool for monitoring webhook events in real-time and forwarding them to development environments.

Installation​

npm install -g @hookvm/cli

Requirements: Node.js ≥18.0.0

Overview​

hookvm [options] [command]

Global Options:

  • -V, --version - Output the version number
  • -h, --help - Display help for command

Default Behavior: When run without arguments, displays welcome message and usage examples:

🔔 hookVM CLI - Webhook monitoring tool

Usage examples:
  hookvm login                                    # Authenticate with hookVM
  hookvm listen <endpoint-url>                    # Monitor webhook events
  hookvm listen <endpoint-url> --target <url>     # Monitor and forward webhooks
  hookvm login status                             # Check authentication status

Endpoint URL formats:
  Private: https://api.example.com/hooks/endpoint-id
  Public:  https://api.example.com/hooks/public/endpoint-id

Core Commands​

hookvm listen​

Monitor webhook events in real-time with an interactive terminal interface.

hookvm listen [options] <endpoint-url>

Arguments:

  • <endpoint-url> (required) - Webhook endpoint URL to monitor

Options:

  • -t, --target <url> - Target URL to forward webhooks to
  • --disable-ui - Disable interactive terminal UI (default: false)
  • -h, --help - Display help for command

URL Format Requirements:

  • Must use HTTP or HTTPS protocol
  • Endpoint ID must be UUID format (8-4-4-4-12 hex characters)
  • Example: https://hookvm.com/hooks/abc123-def456-ghi789-012345

Examples:

# Monitor webhook events with interactive UI
hookvm listen https://hookvm.com/hooks/abc123-def456-ghi789

# Monitor and forward to local development server
hookvm listen https://hookvm.com/hooks/abc123-def456-ghi789 --target http://localhost:3000

# Console mode (no interactive UI) 
hookvm listen https://hookvm.com/hooks/abc123-def456-ghi789 --disable-ui

# Local development endpoint
hookvm listen http://localhost:8080/hooks/abc123-def456-ghi789

Interactive UI Features:

The default interactive mode provides a rich terminal interface with:

  • Real-time Event List: Live webhook events with timestamps and status indicators
  • Request Details: Tabbed view showing Overview, Headers, and Body content
  • Connection Status: WebSocket connection and forwarding status
  • Keyboard Navigation:
    • ↑/↓ or j/k - Navigate event list
    • Tab - Switch between panels
    • Enter - View event details
    • 1,2,3 - Switch detail tabs
    • c - Clear all events
    • h - Show/hide help
    • q - Quit application

Console Mode:

With --disable-ui, outputs simple timestamped events:

[10:30:45] POST from 192.168.1.100
[10:31:02] GET from 203.0.113.50

Connection Process:

  1. Validates endpoint URL format
  2. Extracts endpoint ID and configures WebSocket URL
  3. Establishes WebSocket connection to webhook events
  4. Subscribes to endpoint events
  5. Starts real-time monitoring

Request Forwarding:

When --target is specified, the CLI forwards incoming webhooks to your local server:

  • Headers Filtering: Only essential headers are forwarded for security
  • Custom Headers Added:
    • X-Forwarded-By: webhook-cli
    • X-Original-Endpoint: endpoint-id
  • Timeout: 30 seconds default
  • Success Tracking: Response codes and timing displayed

Essential Headers Forwarded:

  • content-type, user-agent, authorization
  • x-github-event, x-hub-signature, x-hub-signature-256
  • x-stripe-signature, x-webhook-id, x-timestamp
  • accept, accept-encoding

Authentication Commands​

hookvm login​

Authenticate with hookVM using secure browser-based authentication.

hookvm login [options]

Options:

  • -s, --server <url> - Server URL (for testing/custom deployments)
  • -h, --help - Display help for command

Authentication Flow:

  1. Server Selection: Choose from available environments
  2. Browser Authentication: Opens browser for secure OAuth flow
  3. Token Validation: Validates received token with server
  4. Configuration Storage: Saves token to ~/.hookvm/config.json

Available Environments:

  • Production: https://hookvm.com (always available)
  • Development (dev mode only): http://localhost:8080
  • Custom URL (dev mode only): User-entered URL

Example Session:

🔐 Login to hookVM

? What server would you like to authenticate with? hookvm.com
📡 Using server: https://hookvm.com

🌐 Opening browser for authentication...
⏳ Waiting for authentication in browser...
🔍 Validating token...
✓ Authentication successful!
📁 Configuration saved to: /Users/user/.hookvm/config.json

hookvm login status​

Display current authentication status and user information.

hookvm login status

Example Output:

🔐 Authentication Status

Server: https://hookvm.com
Status: Authenticated
User: John Doe (john@example.com)
Token: Valid

Status Information Shown:

  • Current server URL
  • Authentication status (authenticated/not authenticated)
  • User information (name, email)
  • Token validity

hookvm logout​

Sign out of hookVM and clear stored authentication.

hookvm logout

Behavior:

  • Prompts for confirmation
  • Clears stored authentication token
  • Removes user data from configuration

Example:

? Are you sure you want to log out? Yes
✓ Successfully logged out

hookvm auth​

Authentication command group (backward compatibility).

hookvm auth [command]

Available Commands:

  • login - Authenticate with hookVM
  • logout - Sign out of hookVM

Configuration​

Configuration File​

Location: ~/.hookvm/config.json

Structure:

{
  "apiUrl": "https://hookvm.com",
  "wsUrl": "https://hookvm.com/ws",
  "token": "jwt-token-here",
  "currentUser": {
    "id": "user-id", 
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "selectedOrganizationId": "org-id",
  "selectedWorkspaceId": "workspace-id"
}

Environment Detection​

The CLI automatically detects development mode and enables additional features:

Development Mode Detected By:

  • NODE_ENV=development
  • Running from source (not installed via npm)
  • Not running from node_modules directory

Development Mode Features:

  • Access to localhost development server options
  • Custom server URL input
  • Additional debugging information
  • Extended environment selection

Error Handling​

Authentication Errors​

Not authenticated:

❌ Authentication failed 
Please run "hookvm login" to authenticate with hookVM

Invalid/expired token:

Token: Invalid or expired
To re-authenticate, run: hookvm login

URL Validation Errors​

Invalid protocol:

✗ Endpoint URL must use HTTP or HTTPS protocol

Valid examples:
  hookvm listen https://hookvm.com/hooks/your-endpoint-id
  hookvm listen http://localhost:8080/hooks/your-endpoint-id

Invalid endpoint ID format:

✗ Invalid webhook endpoint URL format
Expected format: http://domain.com/endpoint-id

Valid examples:
  hookvm listen https://hookvm.com/hooks/your-endpoint-id
  hookvm listen http://localhost:8080/hooks/your-endpoint-id

Connection Errors​

Connection refused:

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

WebSocket connection timeout:

WebSocket error: Connection timeout

WebSocket URL scheme error:

The URL's scheme must be either 'http:' or 'https:'. 'ws:' is not allowed.

Forwarding Errors​

Invalid target URL:

✗ Invalid target URL format

Target protocol validation:

✗ Target URL must use HTTP or HTTPS protocol

Process Management​

Graceful Shutdown​

The CLI handles shutdown gracefully in both interactive and console modes:

Interactive Mode:

  • Press q or Ctrl+C to quit
  • Automatically disconnects WebSocket and cleans up UI

Console Mode:

  • Press Ctrl+C to stop
  • Handles SIGINT signal for graceful shutdown

Cleanup Process:

  1. Disconnects WebSocket connection
  2. Cleans up terminal UI (if applicable)
  3. Stops request tracking
  4. Exits with appropriate code

Exit Codes:

  • 0 - Success
  • 1 - Error (invalid arguments, connection failure, etc.)

Status Messages​

Connection Status​

  • Connected (Monitoring) - Successfully monitoring webhook events
  • Connected (Monitoring + Forwarding) - Monitoring with forwarding enabled
  • Disconnected: [reason] - Connection lost with reason
  • WebSocket Error: [message] - WebSocket connection error

Forwarding Status​

Interactive UI shows forwarding results:

  • ✅ 200 OK - Successful forwarding with HTTP status
  • ❌ Connection refused - Target server unreachable
  • ⏳ Forwarding to target... - Request in progress

Advanced Usage​

Multiple Endpoints​

Monitor multiple endpoints by running separate CLI instances:

# Terminal 1
hookvm listen https://hookvm.com/hooks/endpoint-1 --target http://localhost:3000

# Terminal 2  
hookvm listen https://hookvm.com/hooks/endpoint-2 --target http://localhost:4000

Development Workflows​

Local Development Server:

# Start your local server
npm run dev

# In another terminal, monitor webhooks and forward to local server
hookvm listen https://hookvm.com/hooks/your-endpoint --target http://localhost:3000

Testing Different Endpoints:

# Test production endpoint with local forwarding
hookvm listen https://hookvm.com/hooks/prod-endpoint --target http://localhost:3000

# Test staging endpoint 
hookvm listen https://staging.hookvm.com/hooks/staging-endpoint --target http://localhost:3000

Console Integration​

For CI/CD or automated testing, use console mode:

# Run in background and log to file
hookvm listen https://hookvm.com/hooks/test-endpoint --disable-ui > webhook-events.log &

# Process webhook events in scripts
hookvm listen https://hookvm.com/hooks/endpoint --disable-ui | grep "POST" | wc -l

Tips and Best Practices​

Performance​

  • Use console mode (--disable-ui) for high-volume endpoints
  • The CLI automatically limits stored events to 1000 to prevent memory issues
  • WebSocket connection includes automatic reconnection with exponential backoff

Security​

  • Authentication tokens are stored securely in your home directory
  • Only essential webhook headers are forwarded to target URLs
  • Maximum 15 headers forwarded to avoid potential issues
  • Custom headers added to identify forwarded requests

Debugging​

  • Use interactive mode for development and debugging
  • Headers and body content are displayed in formatted, readable form
  • Connection status and error messages provide detailed troubleshooting information
  • Press h in interactive mode for keyboard shortcuts help

Development Environment​

  • Use localhost endpoints for local development testing
  • Development mode enables additional server configuration options
  • Custom server URLs supported for enterprise or self-hosted deployments