CLI refactor
This commit is contained in:
466
CLI.md
Normal file
466
CLI.md
Normal file
@@ -0,0 +1,466 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user