CLI Reference

Installation

Install the Unhook CLI globally using your preferred package manager:

npm install -g @unhook/cli

yarn global add @unhook/cli

pnpm add -g @unhook/cli

bun add -g @unhook/cli

deno install @unhook/cli

Quick Start

Initialize your project:

npx @unhook/cli init

Start the webhook:

npx @unhook/cli listen

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)
  -k, --api-key      API key or token for authentication (non-interactive mode)
  -y, --non-interactive  Enable non-interactive mode (disables browser prompts, interactive forms)
  -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

# Non-interactive mode (useful for CI/CD)
npx @unhook/cli init --non-interactive --destination http://localhost:3000/api/webhooks

# Non-interactive mode with API key authentication
npx @unhook/cli init --non-interactive --api-key your_api_key --destination http://localhost:3000/api/webhooks

`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: ".")
  -k, --api-key      API key or token for authentication (non-interactive mode)
  -y, --non-interactive  Enable non-interactive mode (disables keyboard navigation)
  -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

Authenticate your CLI with your Unhook account. Opens a browser for login (unless in non-interactive mode).

unhook login [options]

Options:
  -c, --code         Authentication code for direct login (advanced; usually not needed)
  -k, --api-key      API key or token for authentication (non-interactive mode)
  -y, --non-interactive  Enable non-interactive mode (disables browser opening)
  -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

# Non-interactive login with API key
npx @unhook/cli login --non-interactive --api-key your_api_key

Global Options

Option	Alias	Description	Default
`--verbose`	`-v`	Enable verbose debug logging for troubleshooting	`false`
`--non-interactive`	`-y`	Enable non-interactive mode. Disables browser prompts, interactive forms, and user input. Automatically enabled in CI environments.	`false`
`--api-key`	`-k`	API key or token for authentication in non-interactive mode. Can also be set via `UNHOOK_API_KEY` environment variable.	-
`--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:

unhook.yml (current directory)
unhook.yaml (current directory)
unhook.config.yml (current directory)
unhook.config.yaml (current directory)
unhook.config.js (current directory)
unhook.config.cjs (current directory)
unhook.config.ts (current directory)
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

The CLI supports multiple authentication methods:

Interactive Authentication (Default)

In interactive mode, the CLI uses OAuth browser-based authentication:

Run npx @unhook/cli login or npx @unhook/cli init
A browser window opens for authentication
Complete the OAuth flow in your browser
The CLI automatically receives the authentication token

Non-Interactive Authentication

For CI/CD pipelines, automated scripts, or environments without browser access, use API key authentication: Using API key flag:

npx @unhook/cli init --non-interactive --api-key your_api_key --destination http://localhost:3000

Using environment variable:

export UNHOOK_API_KEY=your_api_key
npx @unhook/cli init --non-interactive --destination http://localhost:3000

Using authentication code:

npx @unhook/cli login --non-interactive --code your_auth_code

In non-interactive mode, if no API key or authentication code is provided, the CLI will display an error message with instructions on how to authenticate.

Authentication Storage

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

CI/CD and Non-Interactive Usage

# Non-interactive initialization with API key
export UNHOOK_API_KEY=your_api_key
npx @unhook/cli init --non-interactive --destination http://localhost:3000/api/webhooks

# Non-interactive initialization with all options
npx @unhook/cli init \
  --non-interactive \
  --api-key $UNHOOK_API_KEY \
  --destination http://localhost:3000/api/webhooks \
  --source stripe \
  --webhook my-webhook-id

# Non-interactive login
npx @unhook/cli login --non-interactive --api-key $UNHOOK_API_KEY

Non-interactive mode is automatically enabled when the CI environment variable is set to true, making it seamless for CI/CD pipelines.

Best Practices

Use Configuration Files: Store your settings in unhook.yml for consistency
Enable Debug Logging: Use --verbose when troubleshooting issues
Health Checks: Configure appropriate health checks for your setup
Environment Variables: Use env vars for sensitive information (e.g., UNHOOK_API_KEY)
Team Configuration: Share configuration files in version control
CI/CD Authentication: Use API keys in CI/CD environments instead of browser-based OAuth
Non-Interactive Mode: Use --non-interactive flag or set CI=true for automated environments

Troubleshooting

Common Issues

Connection Issues
- Check your internet connection
- Verify the webhook ID is correct
- Ensure the port is available
Authentication Problems
- Clear auth data: rm ~/.unhook/auth-storage.json
- Re-run initialization: npx @unhook/cli init
Configuration Issues
- Verify YAML syntax in unhook.yml
- Check file permissions
- Ensure required fields are present
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

Get Started

Reference

Solutions

Development

Installation

Quick Start

Core Commands

`unhook init`

`unhook listen`

Global Options

Configuration

Configuration File

Configuration File Locations

Environment Variables

Interactive UI

UI Elements

Navigation

Health Checks

Authentication

Interactive Authentication (Default)

Non-Interactive Authentication

Authentication Storage

Exit Codes

Examples

Basic Development Setup

Team Development

Custom Configuration

Debug Mode

CI/CD and Non-Interactive Usage

Best Practices

Troubleshooting

Common Issues

Getting Help

Support

​Installation

​Quick Start

​Core Commands

​unhook init

​unhook listen

​unhook login

​Global Options

​Configuration

​Configuration File

​Configuration File Locations

​Environment Variables

​Interactive UI

​UI Elements

​Navigation

​Health Checks

​Authentication

​Interactive Authentication (Default)

​Non-Interactive Authentication

​Authentication Storage

​Exit Codes

​Examples

​Basic Development Setup

​Team Development

​Custom Configuration

​Debug Mode

​CI/CD and Non-Interactive Usage

​Best Practices

​Troubleshooting

​Common Issues

​Getting Help

​Support

Installation

Quick Start

Core Commands

`unhook init`

`unhook listen`

`unhook login`

Global Options

Configuration

Configuration File

Configuration File Locations

Environment Variables

Interactive UI

UI Elements

Navigation

Health Checks

Authentication

Interactive Authentication (Default)

Non-Interactive Authentication

Authentication Storage

Exit Codes

Examples

Basic Development Setup

Team Development

Custom Configuration

Debug Mode

CI/CD and Non-Interactive Usage

Best Practices

Troubleshooting

Common Issues

Getting Help

Support