​
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:
unhook listen
  1. Use the generated webhook URL in your provider’s settings:
https://unhook.sh/wh_your_webhook_id

​
Core Commands

​
Start Webhook

# Basic usage
unhook listen

# With custom client ID
unhook listen --client-id dev-1

# With debug logging
unhook listen --debug

# Redirect to remote URL
unhook --redirect https://api.example.com

​
Initialize Project

# Using npx
npx @unhook/cli init

# Using bunx
bunx @unhook/cli init

# Using pnpm
pnpm dlx @unhook/cli init

# Using deno
deno run --allow-net --allow-read --allow-write npm:@unhook/cli init

​
Command Line Options

OptionAliasDescriptionRequiredDefault
--port-pLocal service portYes*-
--webhook-id-tWebhook IDYes*-
--client-id-cUnique client IDNoAuto-generated
--redirect-rRedirect URLYes*-
--debug-dEnable debug logsNofalse
--ping-Health check configNotrue
--help-hShow helpNo-
--version-vShow versionNo-
* Either --port or --redirect must be provided, but not both.

​
Configuration

​
Configuration File

Create an unhook.yaml in your project root: 
webhookId: "wh_your_webhook_id"
debug: false
telemetry: true
destination:
  - name: "your-endpoint"
    url: "http://localhost:3000/api/webhooks"
source:
  - name: "stripe"
  - name: "github"
delivery:
  - source: "stripe"
    destination: "your-endpoint"
  - source: "github"
    destination: "your-endpoint"

​
Environment Variables

All CLI options can be set via environment variables: 
# Core settings
WEBHOOK_PORT=3000
WEBHOOK_API_KEY=your_api_key
WEBHOOK_CLIENT_ID=dev-1
WEBHOOK_DEBUG=true

# Advanced settings
WEBHOOK_REDIRECT=https://api.example.com
WEBHOOK_PING=true

​
Interactive UI

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

​
UI Elements

  • Status Bar: Shows connection status and client ID
  • Activity Log: Real-time webhook request log
  • Debug Panel: Detailed debug information (visible with --debug)
  • Error Messages: Highlighted in red for visibility

​
Health Checks

The --ping option configures connection health monitoring: 
# Disable health checks
unhook listen --ping false

# Check specific port
unhook listen --ping 3001

# Check specific URL
unhook listen --ping https://api.example.com/health

​
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

# Start webhook on default port
unhook listen --webhook-id your_webhook_id

​
Team Development

# Developer 1
unhook listen --client-id dev1 --webhook-id team_webhook_id

# Developer 2
unhook listen --client-id dev2 --webhook-id team_webhook_id

​
Production Redirect

# Redirect to production API
unhook --redirect https://api.production.com --webhook-id prod_webhook_id

​
Custom Health Checks

# Check specific health endpoint
unhook listen --ping https://localhost:3000/health

​
Best Practices

  1. Use Client IDs: Always specify a meaningful client ID in team environments
  2. Enable Debug Logging: Use --debug when troubleshooting issues
  3. Health Checks: Configure appropriate health checks for your setup
  4. Environment Variables: Use env vars for sensitive information
  5. Configuration Files: Use config files for consistent settings

​
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. Debug Mode
    • Enable debug logging: unhook listen --debug
    • Check the debug panel for detailed information

​
Support