CLI

The HookMyApp CLI is your control plane for WhatsApp and Instagram from the terminal: connect a channel, pull its credentials, stream live webhooks to your laptop, and run a test sandbox, all without leaving your shell.

Building with an AI coding agent? Hand it the agent skills and it can drive every command below for you.

Install

npm install -g @gethookmyapp/cli

Requires Node.js 18 or newer.

Authenticate

# Opens your browser to sign in; the token is stored in your config directory
hookmyapp login
 
# Sign out and remove the stored token
hookmyapp logout

If you are inside an agent that cannot open browser tabs, the CLI prints a URL for you or your operator to open manually.

Workspaces

A workspace is the tenancy boundary for every other command. Pick one before you connect channels.

# List your workspaces and switch the active one
hookmyapp workspace list
hookmyapp workspace use acme
 
# Create, inspect, or rename the active workspace
hookmyapp workspace new "Acme Inc"
hookmyapp workspace current
hookmyapp workspace rename "Acme Corp"

Manage who has access:

hookmyapp workspace members list
hookmyapp workspace members invite teammate@acme.com
hookmyapp workspace members role teammate@acme.com
hookmyapp workspace members remove teammate@acme.com
hookmyapp workspace invites cancel

Channels

Connect your own WhatsApp number or Instagram account, then run per-channel operations. Address a channel by its ID (ch_xxxxxxxx from channels list), its phone, or its @handle.

# Connect through Meta embedded signup (prompts for type if you omit it)
hookmyapp channels connect whatsapp
hookmyapp channels connect instagram
 
# See what you have connected
hookmyapp channels list
hookmyapp channels show ch_xxxxxxxx
 
# Turn forwarding on or off, or disconnect entirely
hookmyapp channels enable ch_xxxxxxxx
hookmyapp channels disable ch_xxxxxxxx
hookmyapp channels disconnect ch_xxxxxxxx

Pull the values your server needs, or check a channel's health:

# Write the channel's env values into a .env file
hookmyapp channels env ch_xxxxxxxx --write .env
 
# Reveal just the access token
hookmyapp channels token ch_xxxxxxxx
 
# Health check: numbers, webhook, quality rating
hookmyapp channels health ch_xxxxxxxx

Receive webhooks

There are two ways to get your own number's inbound messages, depending on where your receiver runs.

For local development, stream webhooks straight to your laptop:

# Opens a secure tunnel and points Meta at it while the CLI runs
hookmyapp channels listen ch_xxxxxxxx

For a deployed receiver, point Meta at your own public URL:

hookmyapp channels webhook set ch_xxxxxxxx \
  --url https://api.acme.com/whatsapp/webhook \
  --verify-token $(openssl rand -hex 32)
 
# Inspect or clear it
hookmyapp channels webhook show ch_xxxxxxxx
hookmyapp channels webhook clear ch_xxxxxxxx

The two are mutually exclusive per channel: setting a URL while channels listen is running reclaims the tunnel.

Read the delivery history:

hookmyapp channels logs list ch_xxxxxxxx
hookmyapp channels logs show <delivery-id>

Sandbox

Test on WhatsApp or Instagram with no Meta setup. See Sandbox for the full flow.

# Start a session and pin it to your phone (prints a bind code + QR)
hookmyapp sandbox start
hookmyapp sandbox start instagram
hookmyapp sandbox status
 
# Pull sandbox env, stream webhooks, send a test message
hookmyapp sandbox env --write .env
hookmyapp sandbox listen
hookmyapp sandbox send --message "hello from my app"
 
# Inspect or end the session
hookmyapp sandbox logs
hookmyapp sandbox stop

The sandbox webhook URL works like a channel's:

hookmyapp sandbox webhook show
hookmyapp sandbox webhook set --url https://example.com/webhook
hookmyapp sandbox webhook clear

Billing

hookmyapp billing status      # your subscription status
hookmyapp billing manage      # open the Stripe customer portal
hookmyapp billing upgrade     # upgrade your plan

Config

Persistent CLI settings.

hookmyapp config show                  # your settings + resolved API URLs
hookmyapp config set telemetry off     # opt out of crash reporting
hookmyapp config set telemetry on      # opt back in

Output formats

Every command takes --json for machine-clean output (notices go to stderr) and --human to force human formatting when stdout is not a TTY. In --json mode, errors use the envelope {"error":{"code":"...","message":"...","status":NNN}}.

hookmyapp channels list --json | jq '.[0].id'

Other global flags: --workspace <slug> overrides the active workspace for one command, and --debug logs the HTTP requests the CLI makes.

Help

# Full command surface
hookmyapp --help
 
# Flags and options for any command
hookmyapp channels webhook set --help

Next steps

  • Sandbox: Start a sandbox session and pull env values.
  • Connect WhatsApp: Connect your own WhatsApp number via embedded signup.