Terminal 1: Start your dev server

Complete reference for all HooksDash CLI commands.

Global Options

Available for all commands:


hooksdash --version, -v    # Show version number
hooksdash --help, -h       # Show help

Authenticate with HooksDash to start using the CLI.

Syntax


hooksdash login [options]

Options

Option	Description	Default
`-k, --api-key <key>`	Manually provide API key (skips browser auth)	Browser authentication
`--api-url <url>`	Custom API URL (for development/self-hosted)	https://hooksdash-api.ibadsiddiqui.dev/api

Examples

Browser authentication (recommended):


hooksdash login

Opens your browser to authenticate. After logging in, your API key is automatically stored.

Manual API key:


hooksdash login --api-key hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Useful for CI/CD environments or if you prefer not to use browser authentication.

Custom API URL (development):


hooksdash login --api-url http://localhost:4000/api

Useful when developing or testing against a local API server.

Output

Success:

✔ Authentication session created
Opening browser for authentication...
✔ Authentication completed!
✔ Successfully authenticated!
Welcome! You're logged in as user@example.com
Tier: FREE

Error:

✖ Authentication failed
Could not connect to HooksDash API
Invalid API key

Notes

Authentication is required before using forward command
API key is stored locally in ~/.config/hooksdash/config.json
Browser authentication sessions expire after 5 minutes
You can re-login at any time to refresh your credentials

`hooksdash logout`

Remove stored credentials from your machine.

Syntax


hooksdash logout

Options

None

Examples


hooksdash logout

Output

Success:

✔ Logged out successfully

Not logged in:

⚠ You are not logged in

Notes

Removes API key from local config file
Does not revoke the API key on the server
To revoke the key, regenerate it in the HooksDash dashboard
You'll need to run hooksdash login again to use the CLI

`hooksdash forward`

Forward webhooks from HooksDash to your local development server.

Syntax


hooksdash forward [options]

Options

Option	Alias	Description	Default
`--port <port>`	`-p`	Local port to forward to	`3000`
`--host <host>`	`-h`	Local host to forward to	`localhost`
`--endpoint <slug>`	`-e`	Endpoint slug to use	Auto-select

Examples

Forward to default port (3000):


hooksdash forward

Forward to custom port:


hooksdash forward --port 4000

Forward to custom host:


hooksdash forward --host 127.0.0.1 --port 8080

Forward specific endpoint:


hooksdash forward --endpoint my-stripe-endpoint

Short options:


hooksdash forward -p 3000 -h localhost -e my-endpoint

Output

Success:

✔ Using endpoint: my-endpoint
Forwarding webhooks to localhost:3000
Connected to HooksDash
Authenticated! Forwarding to localhost:3000
Webhook URL: https://hooksdash.ibadsiddiqui.dev/api/h/my-endpoint
Press Ctrl+C to stop

Receiving webhooks:

← POST /
→ 200

Connection lost:

Connection lost, attempting to reconnect...

Error:

✖ Error: You must be logged in to forward webhooks
Run: hooksdash login

Behavior

Endpoint Selection:

If --endpoint is not provided:

Fetches your existing endpoints
If you have endpoints, uses the first one
If no endpoints exist, creates a new one called "CLI Endpoint"

Connection:

Establishes WebSocket tunnel to HooksDash
Maintains heartbeat to keep connection alive
Automatically reconnects on network interruptions
Gracefully handles server restarts

Request Forwarding:

Preserves HTTP method, headers, and body
Returns response from local server to HooksDash

Notes

You must be logged in to use this command
The endpoint must exist and be active
Your local server must be running on the specified port
Multiple CLI instances can forward different endpoints
Press Ctrl+C to stop forwarding

Stopping the Tunnel

Press Ctrl+C (or Cmd+C on macOS) to stop:

^C
Disconnecting...

`hooksdash status`

Check your current login status.

Syntax


hooksdash status

Options

None

Examples


hooksdash status

Output

Logged in:

✔ Logged in
API Key: hd_abc****xyz

Not logged in:

⚠ Not logged in
Run: hooksdash login

Notes

Shows masked API key (first 7 and last 4 characters)
Quick way to verify authentication before using forward

Common Workflows

Development with Hot Reload


# Terminal 1: Start your dev server
npm run dev  # Runs on port 3000

# Terminal 2: Forward webhooks
hooksdash forward --port 3000

Your webhooks will automatically be forwarded to your hot-reloading dev server.

Multiple Environments


# Development
hooksdash forward --port 3000 --endpoint dev-endpoint

# Staging
hooksdash forward --port 4000 --endpoint staging-endpoint

Testing Different Services


# Terminal 1: Stripe webhooks → Port 3000
hooksdash forward --port 3000 --endpoint stripe-dev

# Terminal 2: GitHub webhooks → Port 4000
hooksdash forward --port 4000 --endpoint github-dev

# Terminal 3: Twilio webhooks → Port 5000
hooksdash forward --port 5000 --endpoint twilio-dev

CI/CD Integration


# Start tunnel in background
hooksdash forward --port 3000 &
TUNNEL_PID=$!

# Run your tests
npm test

# Stop tunnel
kill $TUNNEL_PID

Docker Compose


version: '3.8'
services:
  app:
    build: .
    ports:
      - '3000:3000'
    environment:
      - HOOKSDASH_API_KEY=${HOOKSDASH_API_KEY}
    command: >
      sh -c "
        hooksdash login --api-key $HOOKSDASH_API_KEY &&
        hooksdash forward --port 3000 &
        npm start
      "

Exit Codes

Code	Meaning
0	Success
1	General error
130	Terminated by user (Ctrl+C)

Example


hooksdash forward --port 3000
echo $?  # Prints exit code

Debugging

Verbose Output

For troubleshooting, you can inspect the CLI's network requests:


# Enable debug logs (if implemented)
DEBUG=hooksdash:* hooksdash forward --port 3000

Check Connection

Test if HooksDash API is reachable:


curl https://hooksdash-api.ibadsiddiqui.dev/api/health

Verify Endpoint

Check if your endpoint exists:


# Using your API key
curl -H "X-API-Key: hd_xxx" https://hooksdash-api.ibadsiddiqui.dev/api/endpoints

Tips & Best Practices

Use descriptive endpoint names: Create endpoints with meaningful names like stripe-dev or github-staging
Keep CLI updated: Run npm update -g hooksdash regularly
Use environment variables in CI: Store API key in CI secrets, not in code
One endpoint per service: Don't reuse the same endpoint for multiple webhook sources
Stop tunnels when done: Always stop the tunnel (Ctrl+C) when finished to free up resources
Check status before forwarding: Run hooksdash status to verify you're logged in
Use specific ports: Explicitly specify --port to avoid confusion
Monitor console output: Watch for connection status and errors

Troubleshooting

"You must be logged in"


# Solution:
hooksdash login

"Connection refused" to local server


# Make sure your local server is running
curl http://localhost:3000  # Should return a response

# Start your server
npm run dev

Tunnel disconnects frequently

Check your network connection and firewall settings. The CLI uses WebSocket connections which may be blocked by some firewalls.

Webhooks not being received

Verify endpoint exists: hooksdash status
Check webhook URL is correct in provider's settings
Ensure endpoint is active in HooksDash dashboard
Test with cURL: curl -X POST https://hooksdash.ibadsiddiqui.dev/api/h/your-endpoint

Multiple CLI instances

You can run multiple instances, but each must use a different endpoint:


# Good ✅
hooksdash forward --port 3000 --endpoint endpoint-1
hooksdash forward --port 4000 --endpoint endpoint-2

# Bad ❌ (will conflict)
hooksdash forward --port 3000 --endpoint my-endpoint
hooksdash forward --port 4000 --endpoint my-endpoint

Getting Help

For more help:

Run hooksdash --help or hooksdash <command> --help
Visit HooksDash Documentation
Check GitHub Issues
Contact support: support@hooksdash.ibadsiddiqui.dev

CLI Commands