CLI Reference

​

Installation

Install the Unhook CLI globally using your preferred package manager:

brew install unhook

​

Quick Start

1. Initialize your project:

npx @unhook/cli init

2. Start the webhook:

unhook listen

3. 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

* 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)

​

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

​

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

• Documentation
• GitHub Issues
• Discord Community