whatshooked/CLI.md

# WhatsHooked CLI Documentation

The WhatsHooked CLI provides a command-line interface for managing the WhatsHooked server, webhooks, and WhatsApp accounts.

## Table of Contents

- [Installation](#installation)
- [Authentication](#authentication)
- [Configuration](#configuration)
- [Commands](#commands)
- [Examples](#examples)

## Installation

Build the CLI using the provided Makefile:

```bash
make build
```

The binary will be available at `./bin/whatshook-cli`.

## Authentication

The CLI supports multiple authentication methods to secure communication with the WhatsHooked server.

### Authentication Methods

The CLI supports two authentication methods (in priority order):

1. **API Key Authentication** (Recommended)
   - Uses Bearer token or x-api-key header
   - Most secure and simple to use

2. **Basic Authentication**
   - Uses username and password
   - HTTP Basic Auth

### Configuration Priority

Authentication credentials are loaded in the following priority order (highest to lowest):

1. **Command-line flags** (highest priority)
2. **Environment variables**
3. **Configuration file** (lowest priority)

### Setting Up Authentication

#### Option 1: Configuration File (Recommended)

Create a configuration file at `~/.whatshooked/cli.json`:

```json
{
  "server_url": "http://localhost:8080",
  "auth_key": "your-api-key-here",
  "username": "",
  "password": ""
}
```

Or use API key authentication:

```json
{
  "server_url": "http://localhost:8080",
  "auth_key": "your-secure-api-key"
}
```

Or use username/password authentication:

```json
{
  "server_url": "http://localhost:8080",
  "username": "admin",
  "password": "your-secure-password"
}
```

You can also create a local configuration file in your project directory:

```bash
cp .whatshooked-cli.example.json .whatshooked-cli.json
# Edit the file with your credentials
```

#### Option 2: Environment Variables

Set environment variables (useful for CI/CD):

```bash
export WHATSHOOKED_SERVER_URL="http://localhost:8080"
export WHATSHOOKED_AUTH_KEY="your-api-key-here"
```

Or with username/password:

```bash
export WHATSHOOKED_SERVER_URL="http://localhost:8080"
export WHATSHOOKED_USERNAME="admin"
export WHATSHOOKED_PASSWORD="your-password"
```

#### Option 3: Command-Line Flags

Pass credentials via command-line flags:

```bash
./bin/whatshook-cli --server http://localhost:8080 health
```

Note: Currently, authentication credentials can only be set via config file or environment variables. Command-line flags for auth credentials may be added in future versions.

### No Authentication

If your server doesn't require authentication, simply omit the authentication fields:

```json
{
  "server_url": "http://localhost:8080"
}
```

## Configuration

### Configuration File Locations

The CLI looks for configuration files in the following locations (in order):

1. File specified by `--config` flag
2. `$HOME/.whatshooked/cli.json`
3. `./.whatshooked-cli.json` (current directory)

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `server_url` | string | `http://localhost:8080` | WhatsHooked server URL |
| `auth_key` | string | `""` | API key for authentication |
| `username` | string | `""` | Username for Basic Auth |
| `password` | string | `""` | Password for Basic Auth |

## Commands

### Global Flags

All commands support the following global flags:

- `--config <path>`: Path to configuration file
- `--server <url>`: Server URL (overrides config file)

### Health Check

Check if the server is running and healthy:

```bash
./bin/whatshook-cli health
```

### Hooks Management

#### List Hooks

List all configured webhooks:

```bash
./bin/whatshook-cli hooks
./bin/whatshook-cli hooks list
```

#### Add Hook

Add a new webhook interactively:

```bash
./bin/whatshook-cli hooks add
```

You'll be prompted for:
- Hook ID
- Hook Name
- Webhook URL
- HTTP Method (default: POST)
- Events to subscribe to (optional, comma-separated)
- Description (optional)

**Available Event Types:**

WhatsApp Connection Events:
- `whatsapp.connected` - WhatsApp client connected
- `whatsapp.disconnected` - WhatsApp client disconnected
- `whatsapp.qr.code` - QR code generated for pairing
- `whatsapp.qr.timeout` - QR code expired
- `whatsapp.qr.error` - QR code generation error
- `whatsapp.pair.success` - Device paired successfully
- `whatsapp.pair.failed` - Device pairing failed
- `whatsapp.pair.event` - Generic pairing event

Message Events:
- `message.received` - Message received from WhatsApp
- `message.sent` - Message sent successfully
- `message.failed` - Message sending failed
- `message.delivered` - Message delivered to recipient
- `message.read` - Message read by recipient

Hook Events:
- `hook.triggered` - Hook was triggered
- `hook.success` - Hook executed successfully
- `hook.failed` - Hook execution failed

If no events are specified, the hook will receive all events.

#### Remove Hook

Remove a webhook by ID:

```bash
./bin/whatshook-cli hooks remove <hook_id>
```

### Accounts Management

#### List Accounts

List all configured WhatsApp accounts:

```bash
./bin/whatshook-cli accounts
./bin/whatshook-cli accounts list
```

#### Add Account

Add a new WhatsApp account interactively:

```bash
./bin/whatshook-cli accounts add
```

You'll be prompted for:
- Account ID
- Phone Number (with country code, e.g., +1234567890)
- Session Path (where to store session data)

After adding, check the server logs for a QR code to scan with WhatsApp.

### Send Messages

#### Send Text Message

Send a text message interactively:

```bash
./bin/whatshook-cli send text
```

You'll be prompted for:
- Account ID
- Recipient (phone number or JID)
- Message text

#### Send Image

Send an image with optional caption:

```bash
./bin/whatshook-cli send image <file_path>
```

Supported formats: JPG, PNG, GIF, WebP

#### Send Video

Send a video with optional caption:

```bash
./bin/whatshook-cli send video <file_path>
```

Supported formats: MP4, MOV, AVI, WebM, 3GP

#### Send Document

Send a document with optional caption:

```bash
./bin/whatshook-cli send document <file_path>
```

Supported formats: PDF, DOC, DOCX, XLS, XLSX, TXT, ZIP, and more

## Examples

### Example 1: Basic Setup

```bash
# Create config file
mkdir -p ~/.whatshooked
cat > ~/.whatshooked/cli.json <<EOF
{
  "server_url": "http://localhost:8080",
  "auth_key": "my-secure-api-key"
}
EOF

# Check server health
./bin/whatshook-cli health

# List hooks
./bin/whatshook-cli hooks list
```

### Example 2: Using Environment Variables

```bash
# Set environment variables
export WHATSHOOKED_SERVER_URL="https://my-server.com:8080"
export WHATSHOOKED_AUTH_KEY="production-api-key"

# Use CLI without config file
./bin/whatshook-cli health
./bin/whatshook-cli accounts list
```

### Example 3: Managing Hooks

```bash
# Add a new hook for all events
./bin/whatshook-cli hooks add
# Hook ID: my_hook
# Hook Name: My Webhook
# Webhook URL: https://example.com/webhook
# HTTP Method (POST): POST
# Events (comma-separated, or press Enter for all): [press Enter]
# Description (optional): My webhook handler

# Add a hook for specific events only
./bin/whatshook-cli hooks add
# Hook ID: message_hook
# Hook Name: Message Handler
# Webhook URL: https://example.com/messages
# HTTP Method (POST): POST
# Events (comma-separated, or press Enter for all): message.received, message.sent
# Description (optional): Handle incoming and outgoing messages

# List all hooks
./bin/whatshook-cli hooks

# Remove a hook
./bin/whatshook-cli hooks remove message_hook
```

### Example 4: Sending Messages

```bash
# Send text message
./bin/whatshook-cli send text
# Enter account ID, recipient, and message when prompted

# Send image
./bin/whatshook-cli send image /path/to/photo.jpg

# Send video
./bin/whatshook-cli send video /path/to/video.mp4

# Send document
./bin/whatshook-cli send document /path/to/report.pdf
```

### Example 5: Production Setup with Authentication

```bash
# Server config.json (enable authentication)
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "auth_key": "super-secret-production-key"
  }
}

# CLI config (~/.whatshooked/cli.json)
{
  "server_url": "https://whatshooked.mycompany.com",
  "auth_key": "super-secret-production-key"
}

# Now all CLI commands will be authenticated
./bin/whatshook-cli hooks list
./bin/whatshook-cli accounts add
```

## Error Handling

The CLI provides clear error messages for common issues:

### Authentication Errors

```
Error: HTTP 401: Unauthorized
```

**Solution**: Check your authentication credentials in the config file or environment variables.

### Connection Errors

```
Error: dial tcp: connect: connection refused
```

**Solution**: Ensure the server is running and the URL is correct.

### Invalid Credentials

```
Error: HTTP 403: Forbidden
```

**Solution**: Verify your API key or username/password are correct and match the server configuration.

## Best Practices

1. **Use API Key Authentication**: More secure than username/password, easier to rotate
2. **Store Config Securely**: Don't commit config files with credentials to version control
3. **Use Environment Variables in CI/CD**: Safer than storing credentials in files
4. **Enable Authentication in Production**: Always use authentication for production servers
5. **Use HTTPS**: In production, always use HTTPS for the server URL

## Security Notes

- Never commit configuration files containing credentials to version control
- Use restrictive file permissions for config files: `chmod 600 ~/.whatshooked/cli.json`
- Rotate API keys regularly
- Use different credentials for development and production
- In production, always use HTTPS to encrypt traffic

## Troubleshooting

### Config File Not Found

If you see warnings about config file not being found, create one:

```bash
mkdir -p ~/.whatshooked
cp .whatshooked-cli.example.json ~/.whatshooked/cli.json
# Edit the file with your settings
```

### Server Unreachable

Verify the server is running:

```bash
curl http://localhost:8080/health
```

### Authentication Required

If the server requires authentication but you haven't configured it:

```
Error: HTTP 401: Unauthorized
```

Add authentication to your config file as shown in the [Authentication](#authentication) section.