CLI

Install

npm install -g @gethookmyapp/cli

Requires Node.js 20 or newer.

Authenticate

hookmyapp login
hookmyapp logout

For terminal-only sessions, use hookmyapp login --email <you@example.com>.

Workspaces

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

# List workspaces
hookmyapp workspace list

# Switch active workspace
hookmyapp workspace use acme

# Show active workspace
hookmyapp workspace current

Channels

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

# Connect Instagram account
hookmyapp channels connect instagram

# List connected channels
hookmyapp channels list

# Show channel details
hookmyapp channels show @your-handle

# Enable forwarding
hookmyapp channels enable @your-handle

# Disable forwarding
hookmyapp channels disable @your-handle

# Disconnect channel
hookmyapp channels disconnect @your-handle

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

# Write channel env values
hookmyapp channels env @your-handle --write .env

# Print channel token
hookmyapp channels token @your-handle

# Health check: webhook and channel status
hookmyapp channels health @your-handle

Instagram commands

Use @handle anywhere a command asks for an Instagram channel.

Messages

# Send text DM
hookmyapp instagram messages send --channel @your-handle --to <igsid> --text "hi"

# Mark DM as read
hookmyapp instagram messages read --channel @your-handle --to <igsid>

Comments

# List comments
hookmyapp instagram comments list --channel @your-handle --media <media-id>

# Get comment
hookmyapp instagram comments get <comment-id> --channel @your-handle

# Reply to comment
hookmyapp instagram comments reply --channel @your-handle --comment <comment-id> --text "thanks"

# Hide comment (add --unhide to reverse)
hookmyapp instagram comments hide --channel @your-handle --comment <comment-id>

# Delete comment
hookmyapp instagram comments delete <comment-id> --channel @your-handle

# Send private reply
hookmyapp instagram comments private-reply --channel @your-handle --comment <comment-id> --text "sent you a DM"

Publish

Publish runs the full flow (create container, wait for processing, publish) and prints the permalink.
Media URLs must be public HTTPS. See Publish content for media requirements and quotas.

# Publish image
hookmyapp instagram publish --channel @your-handle --image https://example.com/photo.jpg --caption "New drop"

# Publish reel
hookmyapp instagram publish --channel @your-handle --video https://example.com/reel.mp4 --reel --cover https://example.com/cover.jpg

# Publish story
hookmyapp instagram publish --channel @your-handle --image https://example.com/story.jpg --story

# Publish carousel (prefix video items with video:, plain URLs are images)
hookmyapp instagram publish --channel @your-handle --carousel https://example.com/1.jpg,video:https://example.com/2.mp4 --caption "Gallery"

Insights

See Insights for the metric list and data caveats.

# Account insights
hookmyapp instagram insights --channel @your-handle

# Media insights, chosen metrics
hookmyapp instagram insights --channel @your-handle --media <media-id> --metrics views,reach --json

Receive webhooks

There are two ways to tell HookMyApp where to send inbound DMs for your own account. For local development, send DMs to your laptop while the CLI runs:

# Listen for DMs on your laptop
hookmyapp channels listen @your-handle --path /webhook/instagram

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

# Set deployed webhook URL
hookmyapp channels webhook set @your-handle \
  --url https://api.acme.com/instagram/webhook \
  --verify-token $(openssl rand -hex 32)

# Show webhook URL
hookmyapp channels webhook show @your-handle

# Clear webhook URL
hookmyapp channels webhook clear @your-handle

# Show the HMAC signing secret (used to verify X-HookMyApp-Signature-256)
hookmyapp channels webhook hmac show @your-handle

Use one message destination per channel: either channels listen for local testing or a deployed webhook URL. Read the delivery history:

# List delivery history
hookmyapp channels logs list @your-handle

# Show delivery details
hookmyapp channels logs show <delivery-id>

Sandbox

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

# Start Instagram sandbox
hookmyapp sandbox start instagram

# List sandbox sessions
hookmyapp sandbox status

# Write sandbox env values
hookmyapp sandbox env @your-handle --write .env

# Listen for sandbox DMs
hookmyapp sandbox listen @your-handle --path /webhook/instagram

# Send sandbox test DM
hookmyapp sandbox send @your-handle --message "hello from my app"

# List sandbox deliveries
hookmyapp sandbox logs @your-handle

# Stop sandbox session
hookmyapp sandbox stop @your-handle

The sandbox webhook URL works like a channel webhook URL:

# Show sandbox webhook URL
hookmyapp sandbox webhook show @your-handle

# Set sandbox webhook URL
hookmyapp sandbox webhook set @your-handle --url https://example.com/webhook/instagram

# Clear sandbox webhook URL
hookmyapp sandbox webhook clear @your-handle

Alerts

Your own alert phone: where we reach you if something stops working.

# See your alert phone and what it receives
hookmyapp alerts phone status

# Add or change it (international format)
hookmyapp alerts phone set +14155552671

# Get the code by SMS instead of WhatsApp
hookmyapp alerts phone set +14155552671 --sms

# Finish verification with the code we sent
hookmyapp alerts phone verify 123456

# Remove your alert phone
hookmyapp alerts phone remove

We send a 6-digit code to confirm the number, and set asks for it. In a script there is no prompt: run set with --json, then finish with alerts phone verify <code>. Alerts are on once the number is verified.

Notifications

Notifications from HookMyApp delivered straight to your AI agent, like Claude Code, ChatGPT, or Codex: failing webhooks, disconnected channels, usage limits, and product announcements.

# List open notifications, newest first
hookmyapp notifications

# Include ones already acknowledged
hookmyapp notifications list --all

# Mark a notification seen after relaying it to a human
hookmyapp notifications ack ntf_A1b2C3d4

Acknowledging records that the notification was read. It does not mean the problem is fixed.

Billing

# Show subscription status
hookmyapp billing status

# Open Billing page
hookmyapp billing manage

# Upgrade plan
hookmyapp billing upgrade

Config

Persistent CLI settings.

# Show CLI settings
hookmyapp config show

# Turn telemetry off
hookmyapp config set telemetry off

# Turn telemetry on
hookmyapp config set telemetry on

Output formats

Every command takes --json for machine-clean output 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 an Instagram sandbox session and pull env values.
Connect Instagram: Connect your own Instagram account.
Webhook routing: Route inbound Instagram DMs.

Getting started

Sending & receiving

Publish & engage

Tools

API Reference

Install

Authenticate

Workspaces

Channels

Instagram commands

Messages

Comments

Publish

Insights

Receive webhooks

Sandbox

Alerts

Notifications

Billing

Config

Output formats

Help

Next steps

​Install

​Authenticate

​Workspaces

​Channels

​Instagram commands

​Messages

​Comments

​Publish

​Insights

​Receive webhooks

​Sandbox

​Alerts

​Notifications

​Billing

​Config

​Output formats

​Help

​Next steps

Install

Authenticate

Workspaces

Channels

Instagram commands

Messages

Comments

Publish

Insights

Receive webhooks

Sandbox

Alerts

Notifications

Billing

Config

Output formats

Help

Next steps