Skip to main content

​
Installation

Install the Unhook CLI globally using your preferred package manager: 
npm install -g @unhook/cli

​
Quick Start

  1. Initialize your project:
npx @unhook/cli init
  1. Start the webhook:
npx @unhook/cli listen
  1. Use the generated webhook URL in your provider’s settings:
https://unhook.sh/your_webhook_id

​
Core Commands

​
unhook init

Authenticate with Unhook and set up your project. Creates an unhook.yml config and guides you through connecting your webhook provider. 
unhook init [options]

Options:
  -c, --code         Authentication code for direct login (advanced; usually not needed)
  -t, --destination  Set the local destination URL to forward webhooks to (e.g., "http://localhost:3000/api/webhooks")
  -s, --source       Set the source name or URL for incoming webhooks (e.g., "stripe")
  -w, --webhook      Specify a webhook ID to use (optional; usually auto-generated)
  -v, --verbose      Enable verbose debug logging for troubleshooting
  -h, --help         Show help
Examples: 
# Basic initialization
npx @unhook/cli init

# With custom destination
npx @unhook/cli init --destination http://localhost:3000/api/webhooks

# With specific source
npx @unhook/cli init --source stripe

# With custom webhook ID
npx @unhook/cli init --webhook custom_id

​
unhook listen

Start the Unhook relay to receive and forward webhooks to your local server. Keeps the CLI running and displays incoming requests. 
unhook listen [options]

Options:
  -c, --config       Path to a custom unhook.yml configuration file
  --path             Directory to watch for config changes (default: ".")
  -v, --verbose      Enable verbose debug logging for troubleshooting
  -h, --help         Show help
Examples: 
# Basic usage
npx @unhook/cli listen

# With custom config file
npx @unhook/cli listen --config ./custom/unhook.yml

# With custom directory
npx @unhook/cli listen --path ./config

# With debug logging
npx @unhook/cli listen --verbose

​
unhook login

Authenticate your CLI with your Unhook account. Opens a browser for login. 
unhook login [options]

Options:
  -c, --code         Authentication code for direct login (advanced; usually not needed)
  -v, --verbose      Enable verbose debug logging for troubleshooting
  -h, --help         Show help
Examples: 
# Basic login
npx @unhook/cli login

# With authentication code
npx @unhook/cli login --code your_auth_code

​
Global Options

OptionAliasDescriptionDefault
--verbose-vEnable verbose debug logging for troubleshootingfalse
--help-hShow help-
--version-Show version number-

​
Configuration

​
Configuration File

The CLI uses an unhook.yml file for configuration. This file should be in your project root: 
# Required: Your unique webhook URL
webhookUrl: https://unhook.sh/your-org/your-webhook-name

# Optional: Enable debug mode
debug: false

# Optional: Enable telemetry
telemetry: true

# Required: Array of destination endpoints
destination:
  - name: local
    url: http://localhost:3000/api/webhooks
    ping: true  # Optional: Health check configuration

# Optional: Array of webhook sources
source:
  - name: stripe
  - name: github

# Required: Array of delivery rules
delivery:
  - source: "*"  # Optional: Source filter (defaults to *)
    destination: local  # Name of the destination from 'destination' array

​
Configuration File Locations

The CLI will look for configuration files in the following order:
  1. unhook.yml (current directory)
  2. unhook.yaml (current directory)
  3. unhook.config.yml (current directory)
  4. unhook.config.yaml (current directory)
  5. unhook.config.js (current directory)
  6. unhook.config.cjs (current directory)
  7. unhook.config.ts (current directory)
  8. unhook.config.json (current directory)

​
Environment Variables

All configuration options can be set via environment variables: 
# Core settings
WEBHOOK_URL=https://unhook.sh/your-org/your-webhook-name
WEBHOOK_DEBUG=true
WEBHOOK_TELEMETRY=true

# Destination settings
WEBHOOK_DESTINATION_0_NAME=local
WEBHOOK_DESTINATION_0_URL=http://localhost:3000/api/webhooks
WEBHOOK_DESTINATION_0_PING=true

# Source settings
WEBHOOK_SOURCE_0_NAME=stripe
WEBHOOK_SOURCE_1_NAME=github

# Delivery settings
WEBHOOK_DELIVERY_0_SOURCE=*
WEBHOOK_DELIVERY_0_DESTINATION=local

​
Interactive UI

The CLI includes an interactive terminal UI that shows:
  • Connection status
  • Webhook activity
  • Error messages
  • Debug information (when enabled)

​
UI Elements

  • Status Bar: Shows connection status and client ID
  • Activity Log: Real-time webhook request log
  • Debug Panel: Detailed debug information (visible with --verbose)
  • Error Messages: Highlighted in red for visibility
  • Arrow Keys: Navigate through lists and menus
  • Enter: Select items or execute actions
  • ESC: Go back to previous screen
  • q: Quit the application
  • ?: Show keyboard shortcuts

​
Health Checks

The ping option in your configuration configures connection health monitoring: 
destination:
  - name: local
    url: http://localhost:3000/api/webhooks
    ping: true  # Enable default health check

  - name: custom
    url: http://localhost:3001/api/webhooks
    ping: http://localhost:3001/health  # Custom health check URL

​
Authentication

Authentication data is stored locally at ~/.unhook/auth-storage.json:
  • Authentication state
  • User tokens
  • Organization ID
  • Basic user info
To clear auth data: 
rm ~/.unhook/auth-storage.json

​
Exit Codes

CodeDescription
0Success
1General error
2Invalid configuration
3Network error
4Authentication error

​
Examples

​
Basic Development Setup

# Initialize project
npx @unhook/cli init

# Start webhook
npx @unhook/cli listen

​
Team Development

# Developer 1
npx @unhook/cli init --webhook team_webhook_id
npx @unhook/cli listen

# Developer 2
npx @unhook/cli init --webhook team_webhook_id
npx @unhook/cli listen

​
Custom Configuration

# Use custom config file
npx @unhook/cli listen --config ./config/unhook.yml

# Watch custom directory
npx @unhook/cli listen --path ./config

​
Debug Mode

# Enable debug logging
npx @unhook/cli listen --verbose

# Debug initialization
npx @unhook/cli init --verbose

​
Best Practices

  1. Use Configuration Files: Store your settings in unhook.yml for consistency
  2. Enable Debug Logging: Use --verbose when troubleshooting issues
  3. Health Checks: Configure appropriate health checks for your setup
  4. Environment Variables: Use env vars for sensitive information
  5. Team Configuration: Share configuration files in version control

​
Troubleshooting

​
Common Issues

  1. Connection Issues
    • Check your internet connection
    • Verify the webhook ID is correct
    • Ensure the port is available
  2. Authentication Problems
    • Clear auth data: rm ~/.unhook/auth-storage.json
    • Re-run initialization: npx @unhook/cli init
  3. Configuration Issues
    • Verify YAML syntax in unhook.yml
    • Check file permissions
    • Ensure required fields are present
  4. Debug Mode
    • Enable debug logging: npx @unhook/cli listen --verbose
    • Check the debug panel for detailed information

​
Getting Help

​
Support