meta-cli

Unified CLI for Meta Business APIs: WhatsApp, Instagram, Facebook Pages, and Messenger.

Built with Bun, TypeScript, and yargs. Also available as an OpenClaw skill for agent automation.

Install

Compiled binary (recommended):

git clone https://github.com/adolago/meta-cli.git
cd meta-cli
bun install
bun build --compile --outfile ~/.bun/bin/meta src/index.ts

This produces a standalone binary at ~/.bun/bin/meta that works from any directory without Bun or node_modules.

From npm (global):

bun install -g meta-business-cli

Setup

1. Create a Meta App

Go to Meta for Developers and create a new app (type: Business). Note your App ID and App Secret from Settings > Basic.

2. Configure the CLI

meta config set app.id YOUR_APP_ID
meta config set app.secret YOUR_APP_SECRET

The App ID is numeric (e.g. 755014314346732). The CLI stores config at ~/.meta-cli/config.json.

3. Authenticate

OAuth flow (recommended):

meta auth login

Opens your browser for Meta authorization. The CLI starts a local callback server, receives the auth code, exchanges it for a token, and extends it to a long-lived token (~60 days).

Bring your own token:

meta auth login --token YOUR_ACCESS_TOKEN

Use this if you have a System User token from Meta Business Suite.

4. Configure WhatsApp

From your app's WhatsApp > API Setup page:

• Phone Number ID -- numeric ID shown below the "From" dropdown (e.g. 919256794613473)
• WhatsApp Business Account ID -- shown next to the phone number ID

meta config set whatsapp.phoneNumberId YOUR_PHONE_NUMBER_ID
meta config set whatsapp.businessAccountId YOUR_WABA_ID

Test number setup: Meta provides a test number (+1 555 ...) for free development. To send messages from it, you must first add recipient numbers in the "To" field on the API Setup page. Meta will send a verification code to each recipient. Once verified, you can send to those numbers via the CLI.

Production number: Click "Add phone number" on the API Setup page to register your own business number. You will also need to add a payment method (Step 6 on the dashboard) to send business-initiated messages at scale.

5. Configure other platforms (optional)

# Instagram
meta config set instagram.accountId YOUR_IG_ACCOUNT_ID

# Facebook Pages / Messenger
meta config set pages.pageId YOUR_PAGE_ID

Additional OAuth scopes are needed for non-WhatsApp platforms:

meta auth login --scopes "whatsapp_business_messaging,whatsapp_business_management,instagram_basic,pages_show_list"

6. Verify

meta doctor

All checks should pass. Then test a send:

meta wa send "+1234567890" --template hello_world

Webhooks (receiving messages)

To receive inbound messages, configure a webhook on the API Setup page (Step 3) or use the built-in listener:

meta webhook listen --port 3000 --verify-token MY_TOKEN

Then subscribe to events:

meta webhook subscribe --object whatsapp_business_account --fields messages --callback-url "https://your-domain.com/webhook"

For local development, use --tunnel to expose the listener via a public URL.

Usage

WhatsApp

# Send a text message
meta wa send "+1234567890" --text "Hello from meta-cli"

# Send an image
meta wa send "+1234567890" --image "https://example.com/photo.jpg" --caption "Check this out"

# Send a template
meta wa send "+1234567890" --template hello_world --template-lang en_US

# Manage templates
meta wa template list
meta wa template get my_template

# Upload and manage media
meta wa media upload ./photo.jpg
meta wa media url MEDIA_ID

# Send a local file (auto-uploads)
meta wa send "+1234567890" --document ./report.pdf --caption "Q4 report"

# View analytics
meta wa analytics --days 30

Media File Size Limits

When sending local files, the CLI validates file size before uploading:

Media Type	Max Size
Image	5 MB
Video	16 MB
Document	100 MB

Files exceeding these limits will be rejected with an actionable error. For larger files, host them at a URL and pass the URL directly.

Instagram

# Publish an image
meta ig publish --image "https://example.com/photo.jpg" --caption "My post"

# Publish a Reel
meta ig publish --video "https://example.com/reel.mp4" --reel --caption "New reel"

# View insights
meta ig insights --period day --days 30

# Manage comments
meta ig comments list MEDIA_ID
meta ig comments reply COMMENT_ID "Thanks!"
meta ig comments hide COMMENT_ID

Facebook Pages

# Create a post
meta fb post --message "Hello from meta-cli"

# Create a link post
meta fb post --message "Check this out" --link "https://example.com"

# List posts
meta fb list --limit 10

# View insights
meta fb insights --days 30

Messenger

# Send a message
meta messenger send PSID --text "Hello"

# Send with message tag (outside 24h window)
meta messenger send PSID --text "Update" --type MESSAGE_TAG --tag HUMAN_AGENT

# List conversations
meta messenger receive

Webhooks

# Start a webhook listener
meta webhook listen --port 3000 --verify-token MY_TOKEN --app-secret MY_SECRET

# Subscribe to events
meta webhook subscribe \
  --object whatsapp_business_account \
  --fields messages \
  --callback-url "https://example.com/webhook"

Global Flags

Flag	Description
--json	Output as JSON (for scripting and agent use)
--verbose	Print debug logs to stderr
--token TOKEN	Override stored credentials
--api-version v22.0	Pin a specific Graph API version

OpenClaw Skill

This CLI is also available as an OpenClaw skill for autonomous agent use:

clawhub install meta-business

All commands support --json output for structured, machine-parseable results.

Architecture

src/
├── cli/cmd/          # Thin yargs commands
├── graph/            # Shared Graph API client (retry, pagination, rate limiting)
├── auth/             # OAuth PKCE + encrypted token storage
├── config/           # Zod-validated config (~/.meta-cli/config.json)
├── modules/
│   ├── wa/           # WhatsApp: messages, templates, media, queue
│   ├── ig/           # Instagram: publish, insights, comments
│   ├── fb/           # Facebook Pages: posts, insights
│   └── messenger/    # Messenger: send API, 24h window enforcement
├── webhook/          # Hono server, signature verification, event routing
└── util/             # NamedError, logger, crypto helpers

Development

bun install
bun test          # 60 tests
bun run typecheck # zero errors
bun run dev       # run CLI in dev mode

License

MIT