> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unhook.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Command line interface for Unhook

## Installation

Install the Unhook CLI globally using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @unhook/cli
  ```

  ```bash yarn theme={null}
  yarn global add @unhook/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @unhook/cli
  ```

  ```bash bun theme={null}
  bun add -g @unhook/cli
  ```

  ```bash deno theme={null}
  deno install @unhook/cli
  ```
</CodeGroup>

## Quick Start

1. Initialize your project:

```bash theme={null}
npx @unhook/cli init
```

2. Start the webhook:

```bash theme={null}
npx @unhook/cli listen
```

3. Use the generated webhook URL in your provider's settings:

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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 (unless in non-interactive mode).

```bash theme={null}
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:**

```bash theme={null}
# 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:

```yaml theme={null}
# 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:

```bash theme={null}
# 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:

```yaml theme={null}
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:

1. Run `npx @unhook/cli login` or `npx @unhook/cli init`
2. A browser window opens for authentication
3. Complete the OAuth flow in your browser
4. 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:**

```bash theme={null}
npx @unhook/cli init --non-interactive --api-key your_api_key --destination http://localhost:3000
```

**Using environment variable:**

```bash theme={null}
export UNHOOK_API_KEY=your_api_key
npx @unhook/cli init --non-interactive --destination http://localhost:3000
```

**Using authentication code:**

```bash theme={null}
npx @unhook/cli login --non-interactive --code your_auth_code
```

<Note>
  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.
</Note>

### 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:

```bash theme={null}
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

```bash theme={null}
# Initialize project
npx @unhook/cli init

# Start webhook
npx @unhook/cli listen
```

### Team Development

```bash theme={null}
# 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

```bash theme={null}
# Use custom config file
npx @unhook/cli listen --config ./config/unhook.yml

# Watch custom directory
npx @unhook/cli listen --path ./config
```

### Debug Mode

```bash theme={null}
# Enable debug logging
npx @unhook/cli listen --verbose

# Debug initialization
npx @unhook/cli init --verbose
```

### CI/CD and Non-Interactive Usage

```bash theme={null}
# 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
```

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

## 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 (e.g., `UNHOOK_API_KEY`)
5. **Team Configuration**: Share configuration files in version control
6. **CI/CD Authentication**: Use API keys in CI/CD environments instead of browser-based OAuth
7. **Non-Interactive Mode**: Use `--non-interactive` flag or set `CI=true` for automated environments

## 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](https://docs.unhook.sh)
* **GitHub Issues**: [github.com/unhook-sh/unhook/issues](https://github.com/unhook-sh/unhook/issues)
* **Discord Community**: [discord.gg/unhook](https://discord.gg/unhook)

## Support

* [Documentation](https://docs.unhook.sh)
* [GitHub Issues](https://github.com/unhook-sh/unhook/issues)
* [Discord Community](https://discord.gg/unhook)