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
• Authentication
• Configuration
• Commands
• Examples

Installation

Build the CLI using the provided Makefile:

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:

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

Or use API key authentication:

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

Or use username/password authentication:

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

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

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

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

Or with username/password:

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:

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

{
  "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:

./bin/whatshook-cli health

Hooks Management

List Hooks

List all configured webhooks:

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

Add Hook

Add a new webhook interactively:

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

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

Accounts Management

List Accounts

List all configured WhatsApp accounts:

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

Add Account

Add a new WhatsApp account interactively:

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

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

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

Supported formats: JPG, PNG, GIF, WebP

Send Video

Send a video with optional caption:

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

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

Send Document

Send a document with optional caption:

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

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

Examples

Example 1: Basic Setup

# 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

# 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

# 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

# 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

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

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

Server Unreachable

Verify the server is running:

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