Meta Ads CLI for AI agents (and humans). Analyze ad performance across Meta platforms, pull creative insights with breakdowns, estimate audience reach, retrieve lead form submissions, and more.

Works with: OpenClaw, Claude Code, Cursor, Codex, and any agent that can run shell commands.

npm install -g meta-ads-open-cli

Or run directly: npx meta-ads-open-cli --help

Built on the official Meta Graph API v24.0, this CLI authenticates via an OAuth access token (set as an environment variable, credentials file, or per-command flag) and provides read-only access to the Meta Marketing API.

Core endpoints covered:

• Ad accounts & businesses -- list and inspect ad accounts, business managers, account users
• Campaigns, ad sets & ads -- browse the full campaign hierarchy with status filtering
• Ad creatives -- list and inspect creative assets
• Insights & reporting -- pull performance metrics with date presets, custom date ranges, breakdowns, and time increments
• Audiences -- custom audiences, saved audiences, and reach estimates
• Pixels & conversions -- Meta Pixels, pixel events, and custom conversions
• Pages & Instagram -- Facebook Pages, Instagram business accounts
• Lead gen -- lead forms and lead submissions

export META_ADS_ACCESS_TOKEN="your_access_token"

Create ~/.config/meta-ads-open-cli/credentials.json:

{
  "access_token": "your_access_token"
}

meta-ads-open-cli ad-accounts --credentials /path/to/creds.json

Create a Meta Developer App and request the following permissions:

• ads_read -- Read ad accounts and campaigns
• ads_management -- Required for some read endpoints
• pages_read_engagement -- Read Pages data
• leads_retrieval -- Read lead gen form submissions
• business_management -- Read business accounts

Meta Ads uses this 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). This CLI accepts both act_XXXXX and plain numeric IDs.

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.

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

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

Get the authenticated user or system user info.

meta-ads-open-cli me

List ad accounts the authenticated user has access to.

meta-ads-open-cli ad-accounts

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor

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.

meta-ads-open-cli account-users 123456789 --business 9876543210

Options:

• --business <id> -- business ID associated with this ad account required
• --limit <n> -- results per page (default 100)

List businesses the authenticated user has access to.

meta-ads-open-cli businesses

Options:

• --limit <n> -- results per page (default 100)

List campaigns for an ad account.

meta-ads-open-cli campaigns 123456789
meta-ads-open-cli campaigns 123456789 --status ACTIVE

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor
• --status <status> -- filter by effective_status: ACTIVE, PAUSED, ARCHIVED, DELETED

Get a specific campaign.

meta-ads-open-cli campaign 23851234567890

List ad sets for an ad account.

meta-ads-open-cli adsets 123456789
meta-ads-open-cli adsets 123456789 --campaign 23851234567890

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor
• --campaign <id> -- filter by campaign ID
• --status <status> -- filter by effective_status: ACTIVE, PAUSED, ARCHIVED, DELETED

Get a specific ad set.

meta-ads-open-cli adset 23851234567891

List ads for an ad account.

meta-ads-open-cli ads 123456789
meta-ads-open-cli ads 123456789 --adset 23851234567891

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor
• --adset <id> -- filter by ad set ID
• --status <status> -- filter by effective_status: ACTIVE, PAUSED, ARCHIVED, DELETED

Get a specific ad.

meta-ads-open-cli ad 23851234567892

List ad creatives for an ad account.

meta-ads-open-cli creatives 123456789

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor

Get a specific ad creative.

meta-ads-open-cli creative 23851234567893

Get performance insights for an account, campaign, ad set, or ad.

meta-ads-open-cli insights act_123456789 --date-preset last_30d
meta-ads-open-cli insights 23851234567890 --date-preset last_7d --time-increment 1
meta-ads-open-cli insights act_123456789 --date-preset last_30d --level campaign --breakdowns age,gender

Options:

• --date-preset <preset> -- date range required: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, this_year, last_year, maximum, data_maximum
• --level <level> -- breakdown level: account, campaign, adset, ad
• --breakdowns <breakdowns> -- breakdown dimensions (comma-separated): age, gender, country, region, platform_position, publisher_platform, device_platform, impression_device
• --fields <fields> -- metric fields (comma-separated)
• --time-increment <inc> -- time granularity: any integer 1-90 (days per row, e.g. 1 for daily, 7 for weekly, 14 for bi-weekly), monthly, all_days
• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor

Default metrics: impressions, reach, clicks, cpc, cpm, ctr, spend, actions, cost_per_action_type, conversions, conversion_values, frequency

Get insights with a custom date range.

meta-ads-open-cli insights-date act_123456789 --start 2026-01-01 --end 2026-01-31

Options: same as insights, but uses --start and --end instead of --date-preset.

List custom audiences for an ad account.

meta-ads-open-cli custom-audiences 123456789

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor

Get a specific custom audience.

meta-ads-open-cli custom-audience 23851234567894

List saved audiences for an ad account.

meta-ads-open-cli saved-audiences 123456789

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor

Get reach estimate for targeting specs.

meta-ads-open-cli reach-estimate 123456789 --targeting '{"geo_locations":{"countries":["US"]},"age_min":25,"age_max":45}'

Options:

• --targeting <json> -- targeting spec as JSON string required

List Meta Pixels for an ad account.

meta-ads-open-cli pixels 123456789

Options:

• --limit <n> -- results per page (default 100)

List events received by a Meta Pixel.

meta-ads-open-cli pixel-events 123456789012

List custom conversions for an ad account.

meta-ads-open-cli custom-conversions 123456789

Options:

• --limit <n> -- results per page (default 100)

List Facebook Pages the user manages.

meta-ads-open-cli pages

Options:

• --limit <n> -- results per page (default 100)

Get a specific Facebook Page.

meta-ads-open-cli page 123456789

Get Instagram business account linked to a Facebook Page.

meta-ads-open-cli instagram-accounts 123456789

List lead gen forms for a Facebook Page.

meta-ads-open-cli lead-forms 123456789

Options:

• --limit <n> -- results per page (default 100)

List leads (submissions) for a lead gen form.

meta-ads-open-cli leads 987654321

Options:

• --limit <n> -- results per page (default 100)
• --after <cursor> -- pagination cursor

All errors are JSON to stderr:

{"error": "No credentials found. Set META_ADS_ACCESS_TOKEN env var..."}

• Meta Marketing API Overview
• Ad Insights API
• Custom Audiences API
• Lead Ads API

• google-ads-open-cli -- Google Ads
• tiktok-ads-cli -- TikTok Ads
• snapchat-ads-cli -- Snapchat Ads
• linkedin-ads-cli -- LinkedIn Ads
• pinterest-ads-cli -- Pinterest Ads

Apache-2.0