Meta Ads CLI Skill

You have access to meta-ads-open-cli, a read-only CLI for the Meta Marketing API (Graph API v24.0). Use it to query ad accounts, pull performance insights, inspect creatives, analyze audiences, and retrieve lead form submissions across Facebook, Instagram, Messenger, and Audience Network.

Quick start

# Check if the CLI is available
meta-ads-open-cli --help

# Get authenticated user info
meta-ads-open-cli me

# List accessible ad accounts
meta-ads-open-cli ad-accounts

If the CLI is not installed, install it:

npm install -g meta-ads-open-cli

Authentication

The CLI requires a Meta OAuth access token. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variable: META_ADS_ACCESS_TOKEN
3. Auto-detected file: ~/.config/meta-ads-open-cli/credentials.json

Required permissions depend on the commands used:

• ads_read -- read ad accounts and campaigns
• ads_management -- required for some read endpoints (e.g., ad-specific fields on leads)
• pages_read_engagement -- read Pages data
• leads_retrieval -- read lead gen form submissions
• business_management -- read business accounts

Before running any command, verify credentials are configured by running meta-ads-open-cli me. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Business Manager
 +-- Ad Account (act_XXXXX)
      +-- Campaign
      |    +-- Ad Set
      |         +-- Ad -> Creative
      +-- Custom Audience
      +-- Meta Pixel
      +-- Custom Conversion

Ad account IDs use the act_ prefix (e.g., act_123456789). The CLI accepts both act_XXXXX and plain numeric IDs.

Monetary values

Insights API (spend field): returned as a decimal string in the major currency unit (e.g., "12.34" means $12.34). No conversion needed.

Management API (daily_budget, lifetime_budget, bid_amount): returned as integers in the smallest currency unit (cents). Divide by 100 for the actual amount.

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).

Pagination uses cursor-based --after values from paging.cursors.after in the response.

Commands reference

Account discovery

# Authenticated user info
meta-ads-open-cli me

# List ad accounts
meta-ads-open-cli ad-accounts
meta-ads-open-cli ad-accounts --limit 50

# Get a specific ad account
meta-ads-open-cli ad-account act_123456789
meta-ads-open-cli ad-account 123456789

# List users with access to an ad account (--business is required)
meta-ads-open-cli account-users 123456789 --business 9876543210

# List businesses
meta-ads-open-cli businesses

Campaign hierarchy

# Campaigns (filter by status: ACTIVE, PAUSED, ARCHIVED, DELETED)
meta-ads-open-cli campaigns 123456789
meta-ads-open-cli campaigns 123456789 --status ACTIVE