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:

npx @unhook/cli listen

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

Option	Alias	Description	Default
--verbose	-v	Enable verbose debug logging for troubleshooting	false
--help	-h	Show 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

Navigation

• 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

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

• Documentation: docs.unhook.sh
• GitHub Issues: github.com/unhook-sh/unhook/issues
• Discord Community: discord.gg/unhook

Support

• Documentation
• GitHub Issues
• Discord Community