npm package: @hooklink/cli
Description: Hooklink CLI - Forward webhooks to your local development machine
Author: Hooklink
Latest version: 0.1.68

# Hooklink CLI

Forward webhooks to your local development machine via WebSocket tunnel.

## Installation

```bash
npm install -g @hooklink/cli
```

## Quick Start

1. **Login with your API key:**
   ```bash
   hooklink login
   ```

2. **View your endpoints:**
   ```bash
   hooklink endpoints
   ```

3. **Connect and start forwarding:**
   ```bash
   hooklink connect myapp --target http://localhost:3000
   ```

## Commands

### `hooklink login`

Authenticate with your Hooklink API key.

```bash
# Interactive prompt
hooklink login

# With API key flag
hooklink login --key hlk_your_api_key_here
```

### `hooklink logout`

Clear stored credentials.

```bash
hooklink logout
```

### `hooklink connect [endpoint]`

Connect to Hooklink and forward webhooks to your local server.

```bash
# Connect to specific endpoint
hooklink connect myapp --target http://localhost:3000

# Use port shorthand
hooklink connect myapp --port 3000

# Connect to first active endpoint
hooklink connect --port 8080
```

**Options:**
- `-t, --target <url>` - Local target URL (default: http://localhost:3000)
- `-p, --port <port>` - Local port (alternative to --target)

### `hooklink status`

Show current configuration and connection status.

```bash
hooklink status
```

### `hooklink endpoints`

List all your endpoints.

```bash
hooklink endpoints
# or
hooklink ls
```

### `hooklink logs`

View recent webhook request logs.

```bash
# Show recent logs
hooklink logs

# Filter by endpoint
hooklink logs --endpoint myapp

# Limit number of logs
hooklink logs --limit 50
```

**Options:**
- `-e, --endpoint <keyword>` - Filter by endpoint keyword
- `-l, --limit <number>` - Number of logs to fetch (default: 20)

### `hooklink config`

View or modify CLI configuration.

```bash
# List all configuration
hooklink config

# Get specific value
hooklink config --get apiUrl

# Set configuration value
hooklink config --set apiUrl=https://api.hooklink.net
hooklink config --set defaultPort=8080

# Delete configuration value
hooklink config --delete defaultPort

# Reset all configuration
hooklink config --reset
```

## Configuration

Configuration is stored in `~/.config/hooklink/config.json` (or OS-specific config directory).

**Available configuration keys:**
- `apiKey` - Your Hooklink API key (use `hooklink login` instead)
- `apiUrl` - API base URL (default: https://api.hooklink.net)
- `wsUrl` - WebSocket server URL (default: wss://ws.hooklink.net/ws)
- `defaultEndpoint` - Default endpoint keyword to connect to
- `defaultPort` - Default local port (default: 3000)

## How It Works

1. The CLI establishes a WebSocket connection to the Hooklink server
2. When a webhook arrives at your public URL, the server forwards it through the WebSocket
3. The CLI receives the webhook and forwards it to your local server
4. The response from your local server is sent back through the WebSocket
5. Hooklink returns the response to the original webhook sender

## Troubleshooting

### Connection Issues

- Ensure you're logged in: `hooklink login`
- Check your endpoint is active: `hooklink endpoints`
- Verify your local server is running
- Check WebSocket URL: `hooklink config --get wsUrl`

### Authentication Errors

- Verify your API key is valid: `hooklink status`
- Re-login if needed: `hooklink logout && hooklink login`

### Request Not Forwarding

- Check logs: `hooklink logs`
- Ensure your endpoint URL matches the webhook source
- Verify source whitelist settings in the dashboard

## Examples

### Basic Usage

```bash
# Login
hooklink login --key hlk_your_api_key

# Start forwarding to localhost:3000
hooklink connect myapp

# Start forwarding to different port
hooklink connect myapp --port 8080
```

### Custom Configuration

```bash
# Set custom API URL (for self-hosted)
hooklink config --set apiUrl=https://api.yourdomain.com
hooklink config --set wsUrl=wss://ws.yourdomain.com

# Set default port
hooklink config --set defaultPort=8080

# Now connect uses your defaults
hooklink connect myapp
```

### Viewing Logs

```bash
# View recent logs
hooklink logs

# View logs for specific endpoint
hooklink logs --endpoint myapp

# View more logs
hooklink logs --limit 100
```

## License

MIT