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.

Installation

npm install -g meta-ads-open-cli

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

How it works

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

Setup

Option 1: Environment variable

export META_ADS_ACCESS_TOKEN="your_access_token"

Option 2: Credentials file

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

{
  "access_token": "your_access_token"
}

Option 3: Per-command credentials

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

Getting an access token

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

Entity hierarchy

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.

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.

Usage

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.

me

Get the authenticated user or system user info.

meta-ads-open-cli me

ad-accounts

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

ad-account

Get a specific ad account.

meta-ads-open-cli ad-account act_123456789
meta-ads-open-cli ad-account 123456789

account-users

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)

businesses

List businesses the authenticated user has access to.

meta-ads-open-cli businesses

Options:

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

campaigns

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

campaign

Get a specific campaign.

meta-ads-open-cli campaign 23851234567890

adsets

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

adset

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

creatives

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

creative

Get a specific ad creative.

meta-ads-open-cli creative 23851234567893

insights

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

insights-date

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.

custom-audiences

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

custom-audience

Get a specific custom audience.

meta-ads-open-cli custom-audience 23851234567894

saved-audiences

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

reach-estimate

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

pixels

List Meta Pixels for an ad account.

meta-ads-open-cli pixels 123456789

Options:

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

pixel-events

List events received by a Meta Pixel.

meta-ads-open-cli pixel-events 123456789012

custom-conversions

List custom conversions for an ad account.

meta-ads-open-cli custom-conversions 123456789

Options:

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

pages

List Facebook Pages the user manages.

meta-ads-open-cli pages

Options:

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

page

Get a specific Facebook Page.

meta-ads-open-cli page 123456789

instagram-accounts

Get Instagram business account linked to a Facebook Page.

meta-ads-open-cli instagram-accounts 123456789

lead-forms

List lead gen forms for a Facebook Page.

meta-ads-open-cli lead-forms 123456789

Options:

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

leads

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

Error output

All errors are JSON to stderr:

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

API Reference

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

License

Apache-2.0

Keywords

FAQs

What is meta-ads-open-cli?

Is meta-ads-open-cli well maintained?

Package last updated on 19 Mar 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

meta-ads-open-cli

meta-ads-open-cli

Installation

How it works

Setup

Option 1: Environment variable

Option 2: Credentials file

Option 3: Per-command credentials

Getting an access token

Entity hierarchy

Monetary values

Usage

me

ad-accounts

ad-account

account-users

businesses

campaigns

campaign

adsets

adset

ads

ad

creatives

creative

insights

insights-date

custom-audiences

custom-audience

saved-audiences

reach-estimate

pixels

pixel-events

custom-conversions

pages

page

instagram-accounts

lead-forms

leads

Error output

API Reference

Related

License

Keywords

Related posts

Fake Braintree NuGet Package Skims Credit Cards and Harvests Merchant Credentials

Compromised Injective SDK npm Package Exfiltrates Wallet Keys and Mnemonics