meta-ads-cli

A command-line interface for managing Meta (Facebook/Instagram) Ads accounts. Designed for AI agents and automation workflows, with structured JSON output by default.

Disclaimer: This is an unofficial, community-maintained tool and is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. "Meta", "Facebook", and "Instagram" are trademarks of Meta Platforms, Inc.

Installation

npm install -g meta-ads-cli

Or run directly with npx:

npx meta-ads-cli campaigns list

Quick Start

1. Get an Access Token

1. Go to Meta Business Suite > Business Settings
2. Navigate to Users > System Users
3. Create or select a System User
4. Generate a token with ads_management and ads_read permissions

2. Authenticate

meta-ads auth login --token YOUR_ACCESS_TOKEN

3. Set Default Account

meta-ads accounts list
meta-ads accounts switch act_123456789

4. Start Using

# List campaigns
meta-ads campaigns list

# Get campaign details
meta-ads campaigns get 120210123456789

# Pause a campaign
meta-ads campaigns pause 120210123456789

# Get performance metrics
meta-ads insights get --level campaign --date-preset last_7d

Commands

Authentication

meta-ads auth login              # Interactive token input
meta-ads auth login --token XXX  # Direct token input
meta-ads auth status             # Check authentication status
meta-ads auth logout             # Remove stored token

Configuration

meta-ads config set account_id act_123456789
meta-ads config set output_format table
meta-ads config get account_id
meta-ads config list

Accounts

meta-ads accounts list
meta-ads accounts get act_123456789
meta-ads accounts switch act_123456789

Campaigns

meta-ads campaigns list
meta-ads campaigns list --status ACTIVE
meta-ads campaigns list --output table
meta-ads campaigns get 120210123456789
meta-ads campaigns create --name "Q1 Brand" --objective OUTCOME_AWARENESS
meta-ads campaigns update 120210123456789 --name "Updated Name"
meta-ads campaigns pause 120210123456789
meta-ads campaigns activate 120210123456789

Ad Sets

meta-ads adsets list
meta-ads adsets list --campaign 120210123456789
meta-ads adsets get 120310123456789
meta-ads adsets pause 120310123456789
meta-ads adsets activate 120310123456789

Ads

meta-ads ads list
meta-ads ads list --adset 120310123456789
meta-ads ads get 120410123456789
meta-ads ads pause 120410123456789
meta-ads ads activate 120410123456789

Ad Creatives

meta-ads adcreatives list
meta-ads adcreatives get 120510123456789

Insights

meta-ads insights get --level campaign --date-preset last_7d
meta-ads insights get --level ad --date-range 2025-01-01:2025-01-31
meta-ads insights get --level adset --breakdowns age,gender

Bulk Operations

meta-ads bulk pause --type campaign --ids 123,456,789
meta-ads bulk activate --type adset --ids 123,456
meta-ads bulk export --type campaigns --status ACTIVE --output-file campaigns.json

Output Formats

JSON (default)

meta-ads campaigns list

{
  "success": true,
  "data": [
    {
      "id": "120210123456789",
      "name": "Q1 Brand Campaign",
      "status": "ACTIVE",
      "objective": "OUTCOME_AWARENESS"
    }
  ],
  "meta": {
    "account_id": "act_123456789",
    "timestamp": "2025-01-04T12:00:00.000Z"
  }
}

Table

meta-ads campaigns list --output table

┌────────────────────┬─────────────────────┬────────┬─────────────────────┐
│ ID                 │ Name                │ Status │ Objective           │
├────────────────────┼─────────────────────┼────────┼─────────────────────┤
│ 120210123456789    │ Q1 Brand Campaign   │ ACTIVE │ OUTCOME_AWARENESS   │
└────────────────────┴─────────────────────┴────────┴─────────────────────┘

Configuration

Configuration priority (highest to lowest):

1. Command flags: --account act_123
2. Environment variables: META_ADS_ACCOUNT_ID=act_123
3. Config file: ~/.config/meta-ads/config.json

Environment Variables

META_ADS_ACCESS_TOKEN   # Access token
META_ADS_ACCOUNT_ID     # Default ad account
META_ADS_OUTPUT         # Output format (json/table)
META_ADS_VERBOSE        # Enable verbose output (true/false)
META_ADS_API_VERSION    # API version (default: v22.0)

Global Flags

-a, --account   Ad account ID
-o, --output    Output format (json/table)
-v, --verbose   Enable verbose output
-q, --quiet     Suppress non-essential output

Error Handling

Errors are returned as structured JSON:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests to Meta API.",
    "details": {
      "suggestion": "Wait before retrying. Check the retry_after value."
    },
    "retry_after": 60
  }
}

Use with AI Agents

This CLI is designed to be used by AI agents like Claude Code. The structured JSON output makes it easy to parse and act upon:

# Get active campaigns as JSON for parsing
meta-ads campaigns list --status ACTIVE

# Pause campaigns programmatically
meta-ads campaigns pause 120210123456789

# Get performance data for analysis
meta-ads insights get --level campaign --date-preset last_30d

Development

# Clone the repository
git clone https://github.com/your-org/meta-ads-cli.git
cd meta-ads-cli

# Install dependencies
npm install

# Build
npm run build

# Run locally
./bin/run.js campaigns list

License

MIT