CLI Reference

Command line interface for Unhook

Installation

Install the Unhook CLI globally using your preferred package manager:

npm

npm install -g @unhook/cli

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

Option	Alias	Description	Required	Default
--port	-p	Local service port	Yes*	-
--webhook-id	-t	Webhook ID	Yes*	-
--client-id	-c	Unique client ID	No	Auto-generated
--redirect	-r	Redirect URL	Yes*	-
--debug	-d	Enable debug logs	No	false
--ping	-	Health check config	No	true
--help	-h	Show help	No	-
--version	-v	Show version	No	-

* 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

Code	Description
0	Success
1	General error
2	Invalid configuration
3	Network error
4	Authentication 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

• Documentation
• GitHub Issues
• Discord Community

Assistant

Responses are generated using AI and may contain mistakes.