What is the Meta Ads CLI?

The Meta Ads CLI is an official command-line tool released by Meta in April 2026 that wraps the Meta Marketing API into a single executable program. It allows developers and AI agents to create, edit, and analyze Facebook ad campaigns directly from the terminal without writing custom API code.

What are the system requirements for Meta CLI?

Meta CLI requires Python 3.12 or higher and can be installed via pip or uv. It works on Windows, macOS, and Linux. You also need a Meta Business account with ad account access and a Meta Developer app with system user credentials.

How do I install the Meta Ads CLI?

Install Python 3.12+, then run pip install meta-ads-cli in your terminal. Create a Meta Developer app, set up a system user in Business Manager, generate an access token, then authenticate with meta auth login and configure your default account.

What commands are available in Meta CLI?

Key commands include: meta ads campaign list/create/edit, meta ads insights get for performance data, meta ads creative upload for ad creatives, meta commerce catalog create for product catalogs, and meta datasets create for conversion tracking. All commands support --format json and automation flags.

Can AI agents use the Meta CLI?

Yes, the Meta CLI is specifically designed for AI agent integration. It provides predictable exit codes, suppressed prompts for automation, structured JSON output, and works with Claude Code, Cursor, and other AI development tools. All campaigns created by AI default to PAUSED status for safety.

How does Meta CLI compare to the Meta Marketing API?

Meta CLI wraps the Marketing API and handles authentication, pagination, output formatting, and error handling automatically. Instead of writing custom API code, you can run simple commands like meta ads campaign list. It is faster for prototyping and automation but provides the same underlying functionality as direct API access.

MCP

Meta CLI — Command-Line Tool for Meta Ads Automation & AI Agent Integration

Meta CLI is Meta's official command-line tool for automating ad campaigns directly from the terminal. Released April 2026, it wraps the Marketing API into simple commands that developers and AI agents use to create, edit, and analyze campaigns without custom code.

Ira Bodnar·May 9, 2026·Updated May 9, 2026·18 min read

Contents

Autonomous Marketing

Grow your business faster with AI agents

✓Automates Google, Meta + 5 more platforms
✓Handles your SEO end to end
✓Upgrades your website to convert better

What is Meta CLI and why did Meta build it?

Meta CLI is Meta's official command-line tool for managing Meta Ads campaigns, launched April 29, 2026. It packages the Meta Marketing API into a single executable that developers and AI agents can use to create, edit, and analyze campaigns directly from the terminal. Instead of writing custom code to handle authentication, pagination, and output formatting, you run commands like meta ads campaign list and get structured results immediately.

The tool was developed by Meta's platform team (John Holstein, Matt Mayberry, Andrew Kutsy, and Sanjay Patel) to solve a specific problem: developers were writing the same boilerplate code repeatedly to interact with the Marketing API. Every integration required custom authentication flows, error handling, pagination logic, and output formatting. Meta CLI abstracts all that complexity into predictable commands that work in shell scripts, CI/CD pipelines, and AI agent workflows.

What makes meta cli — command-line tool for meta ads automation particularly powerful is its design for unattended execution. Unlike the Meta Ads Manager interface, which requires human interaction, the CLI handles batch operations, returns structured data (table, JSON, or plain text), and provides proper exit codes for automation. It requires Python 3.12+ and connects to the same API endpoints as Meta's web interface, but optimized for programmatic access.

The timing of the release aligns with Meta's broader AI strategy. As companies deploy AI agents to manage ad spend — which reached $181 billion globally in 2025 — Meta needed developer-friendly tools that agents could invoke reliably. The CLI serves this need while maintaining the security and permission controls of the Marketing API. For context on alternative approaches, see our guide on How to Use Claude for Meta Ads.

1,000+ Marketers Use Ryze

Automating hundreds of agencies

★★★★★4.9/5

How do you install and configure Meta CLI?

Installing meta cli — command-line tool for meta ads automation requires Python 3.12 or higher and involves a one-time authentication setup through Meta's Developer Portal. The entire process takes 10-15 minutes if you already have a Meta Business account with ad access. Most of the setup time involves creating the necessary credentials rather than the technical installation.

Step 1: Install Python 3.12+

Check your Python version with python --version. If you're running anything below 3.12, download the latest from python.org. Meta CLI uses modern Python features that require this minimum version.

Step 2: Install Meta CLI

# Using pip pip install meta-ads-cli # Using uv (faster) uv add meta-ads-cli # Verify installation meta --version

Step 3: Create Meta Developer App

Navigate to developers.facebook.com > My Apps > Create App. Choose "Business" as the app type. This creates a container for your CLI credentials. You'll need App ID and App Secret from the dashboard.

Step 4: Create System User

In Meta Business Manager > Business Settings > Users > System Users, create a new system user. Assign it Admin access to your ad account(s) and add it as an App Admin in your developer app. System users allow programmatic access without requiring personal Facebook login.

Step 5: Generate Access Token

From your system user's page, generate an access token with these 7 required scopes:

ads_management
ads_read
business_management
catalog_management
pages_read_engagement
pages_manage_posts
leads_retrieval

Save this token securely — it provides full access to your ad accounts. Set it as an environment variable or store it in a .env file in your project directory.

Step 6: Configure Authentication

# Set environment variables export META_ACCESS_TOKEN="your_token_here" export META_AD_ACCOUNT_ID="act_1234567890" # Or use CLI login (opens browser OAuth) meta auth login # Set default account meta config set default_account act_1234567890

Step 7: Test Your Setup

# List your campaigns meta ads campaign list # Get account info meta ads account info

If you see your campaign data, you're ready to automate. If you get authentication errors, double-check your token scopes and ad account permissions.

Tools like Ryze AI automate this entire workflow — connecting to Meta, monitoring performance, and optimizing campaigns 24/7 without manual CLI commands. Ryze AI clients see an average 3.8x ROAS improvement within 6 weeks of onboarding.

What are the most useful Meta CLI commands for automation?

Meta CLI organizes commands around Meta's object hierarchy: campaigns > ad sets > ads > creatives. Each object type supports standard CRUD operations (create, read, update, delete) plus specialized commands for insights and bulk operations. The commands below represent 80% of typical automation workflows.

Campaign Management

# List all campaigns meta ads campaign list # Create a new campaign meta ads campaign create \ --name "Q2 Retargeting Campaign" \ --objective OUTCOME_SALES \ --daily-budget 5000 \ --status PAUSED # Update campaign budget meta ads campaign update CAMPAIGN_ID \ --daily-budget 7500 # Get campaign performance meta ads insights get \ --campaign_id CAMPAIGN_ID \ --date-preset last_30d \ --fields impressions,spend,conversions,cost_per_conversion \ --format json

Ad Set Operations

# List ad sets for a campaign meta ads adset list --campaign_id CAMPAIGN_ID # Create targeted ad set meta ads adset create \ --campaign_id CAMPAIGN_ID \ --name "LAL 1% - US - Ages 25-44" \ --daily-budget 1000 \ --optimization-goal CONVERSIONS \ --targeting '{"geo_locations":{"countries":["US"]},"age_min":25,"age_max":44}' # Update ad set bid strategy meta ads adset update ADSET_ID \ --bid-strategy LOWEST_COST_WITHOUT_CAP

Performance Analysis

# Account-level insights with breakdowns meta ads insights get \ --level account \ --date-preset last_7d \ --breakdowns age,gender \ --fields reach,frequency,cpm,ctr,conversions # Ad-level creative performance meta ads insights get \ --level ad \ --date-preset yesterday \ --fields ad_name,impressions,clicks,ctr,conversions \ --sort "-ctr" \ --limit 20 # Custom date range with time increments meta ads insights get \ --campaign_id CAMPAIGN_ID \ --time-range '{"since":"2026-05-01","until":"2026-05-07"}' \ --time-increment daily \ --fields spend,impressions,conversions

Bulk Operations

# Pause all ad sets in a campaign meta ads adset list --campaign_id CAMPAIGN_ID --format json | \ jq -r '.[].id' | \ xargs -I {} meta ads adset update {} --status PAUSED # Bulk budget updates from CSV while IFS=, read -r adset_id new_budget; do meta ads adset update "$adset_id" --daily-budget "$new_budget" done < budget_changes.csv # Export all campaign data for analysis meta ads campaign list --format json > campaigns.json meta ads insights get --level campaign \ --date-preset last_30d \ --fields spend,impressions,conversions,cost_per_conversion \ --format json > campaign_performance.json

Catalog & Creative Management

# Create product catalog meta ads catalog create --name "Summer Collection 2026" # Add products to catalog meta ads product create CATALOG_ID \ --name "Premium Bluetooth Headphones" \ --price "199.99" \ --currency "USD" \ --availability "in stock" # Upload ad creative meta ads creative create \ --name "Video Creative - Product Demo" \ --object-story-spec '{"page_id":"PAGE_ID","video_data":{"video_id":"VIDEO_ID"}}' \ --degrees-of-freedom-spec '{"creative_features_spec":{"standard_enhancements":{"enroll_status":"OPT_IN"}}}'

Each command returns structured data that you can pipe into other tools (jq for JSON processing, awk for text manipulation) or feed into AI agents for analysis. The --format json flag is particularly useful for automation workflows that need to process the output programmatically.

Ryze AI — Autonomous Marketing

Skip the CLI commands — let AI optimize your Meta Ads 24/7

✓Automates Google, Meta + 5 more platforms
✓Handles your SEO end to end
✓Upgrades your website to convert better

2,000+

Marketers

$500M+

Ad spend

Countries

How do AI agents use Meta CLI for automated campaign management?

Meta CLI was explicitly designed for AI agent integration. Unlike web interfaces that require complex browser automation, the CLI provides deterministic commands with predictable outputs that agents can invoke reliably. Claude Code, Cursor, OpenAI's Codex, and other AI development tools can read Meta CLI documentation, execute commands, and parse results without human intervention.

The key advantage is structured output formats. When an AI agent runs meta ads campaign list --format json, it receives machine-readable data that it can analyze, filter, and act upon. Exit codes (0 for success, 3 for auth errors, 4 for API errors) allow agents to handle failures gracefully and retry with different parameters.

Skill File Integration

AI agents work best with skill files — predefined templates that specify exactly how to use meta cli — command-line tool for meta ads automation. Here's a sample skill file for Claude Code:

# META_ADS_SKILL.md ## Meta Ads CLI Skill This skill enables Claude to manage Meta Ads campaigns via command line. ### Available Commands: - Campaign analysis: `meta ads insights get --campaign_id ID --fields metrics` - Budget updates: `meta ads campaign update ID --daily-budget AMOUNT` - Performance reporting: `meta ads insights get --level account --format json` ### Safety Rules: 1. Always use --status PAUSED when creating new campaigns 2. Confirm budget changes > $1000 with user before executing 3. Export data before making bulk changes 4. Use date-preset last_7d for trend analysis ### Output Processing: - Pipe JSON output to jq for filtering: `command | jq '.[] | select(.spend > 100)'` - Sort results: `--sort "-spend"` for highest spend first - Limit results: `--limit 50` for top performers

Automated Workflow Example

Here's how an AI agent might automate creative fatigue detection using Meta CLI:

#!/bin/bash # AI Agent Creative Fatigue Detection Workflow # Step 1: Get all active ads with 7-day performance meta ads insights get \ --level ad \ --date-preset last_7d \ --fields ad_name,ad_id,ctr,frequency,impressions \ --filter '[{"field":"ad.status","operator":"EQUAL","value":"ACTIVE"}]' \ --format json > current_performance.json # Step 2: Get 14-day performance for comparison meta ads insights get \ --level ad \ --date-preset last_14d \ --fields ad_name,ad_id,ctr,frequency \ --filter '[{"field":"ad.status","operator":"EQUAL","value":"ACTIVE"}]' \ --format json > historical_performance.json # Step 3: Analyze for fatigue (CTR decline > 20%, frequency > 3.0) jq -r ' .[] | select(.frequency > 3.0) | select(.ctr < (.historical_ctr * 0.8)) | [.ad_id, .ad_name, .ctr, .frequency] | @csv ' performance_analysis.json > fatigued_ads.csv # Step 4: Pause fatigued ads while IFS=, read -r ad_id ad_name ctr frequency; do echo "Pausing fatigued ad: $ad_name (CTR: $ctr, Freq: $frequency)" meta ads ad update "$ad_id" --status PAUSED done < fatigued_ads.csv

Error Handling & Safety

Production AI agents need robust error handling when using Meta CLI. The tool provides specific exit codes and error messages that agents can parse:

# Exit code handling in bash meta ads campaign update CAMPAIGN_ID --daily-budget 10000 exit_code=$? case $exit_code in 0) echo "Budget update successful" ;; 3) echo "Authentication failed - refresh token" ;; 4) echo "API error - check rate limits" ;; *) echo "Unknown error - manual intervention required" ;; esac

Smart agents implement circuit breakers: if 3 consecutive API calls fail, they pause automation and alert humans. They also maintain audit logs of all changes for compliance and rollback capability.

What automation workflows can you build with Meta CLI?

Meta CLI excels at automation workflows that require data analysis, pattern recognition, and systematic changes across multiple campaigns. These workflows typically run on schedules (via cron jobs) or triggers (webhook responses). The examples below represent real workflows that marketing teams deploy in production environments.

Workflow 01

Daily Budget Rebalancing

This workflow runs every morning at 9 AM, analyzes yesterday's performance, and redistributes budget toward high-performing ad sets. It prevents budget waste by moving money away from ad sets with CPA > target thresholds toward those converting efficiently.

# Daily budget rebalancing script #!/bin/bash TARGET_CPA=45 # Your target cost per acquisition TOTAL_BUDGET=5000 # Total daily budget to allocate # Get yesterday's performance by ad set meta ads insights get \ --level adset \ --date-preset yesterday \ --fields adset_id,adset_name,conversions,spend,cost_per_conversion \ --filter '[{"field":"adset.status","operator":"EQUAL","value":"ACTIVE"}]' \ --format json > adset_performance.json # Calculate budget allocation based on efficiency jq -r --argjson target_cpa $TARGET_CPA --argjson total_budget $TOTAL_BUDGET ' map(select(.conversions > 0 and .cost_per_conversion <= $target_cpa)) | map(.efficiency = 1 / .cost_per_conversion) | (map(.efficiency) | add) as $total_efficiency | map(.new_budget = ((.efficiency / $total_efficiency) * $total_budget | floor)) | .[] | [.adset_id, .new_budget] | @csv ' adset_performance.json > budget_allocation.csv # Apply new budgets while IFS=, read -r adset_id new_budget; do meta ads adset update "$adset_id" --daily-budget "$new_budget" done < budget_allocation.csv

Workflow 02

Weekly Stakeholder Reports

Generates comprehensive reports every Monday morning with account performance, top campaigns, budget utilization, and recommendations. The report is automatically formatted and emailed to stakeholders, eliminating 2-3 hours of manual work per week.

# Weekly report generation meta ads insights get \ --level account \ --date-preset last_week \ --fields spend,impressions,clicks,conversions,cost_per_conversion \ --format json > weekly_summary.json # Campaign-level breakdown meta ads insights get \ --level campaign \ --date-preset last_week \ --fields campaign_name,spend,conversions,cost_per_conversion \ --sort "-spend" \ --limit 20 \ --format json > top_campaigns.json # Generate HTML report python generate_report.py weekly_summary.json top_campaigns.json > weekly_report.html # Email to stakeholders curl -X POST https://api.mailgun.net/v3/yourdomain.com/messages \ -F from="reporting@yourcompany.com" \ -F to="team@yourcompany.com" \ -F subject="Meta Ads Weekly Report - $(date +%Y-%m-%d)" \ -F html="$(cat weekly_report.html)"

Workflow 03

Audience Overlap Detection

Identifies ad sets targeting similar audiences that compete against each other in Meta's auction. When overlap exceeds 20%, the workflow recommends consolidation or exclusion strategies to reduce CPM inflation.

# Extract targeting criteria from all active ad sets meta ads adset list \ --fields id,name,targeting,daily_budget \ --filter '[{"field":"adset.status","operator":"EQUAL","value":"ACTIVE"}]' \ --format json > adset_targeting.json # Python script to calculate overlap python - << 'EOF' import json import sys with open('adset_targeting.json') as f: adsets = json.load(f) # Simplified overlap detection (full implementation would use Sets API) overlaps = [] for i, adset1 in enumerate(adsets): for adset2 in adsets[i+1:]: targeting1 = adset1.get('targeting', {}) targeting2 = adset2.get('targeting', {}) # Check for similar demographics, interests, behaviors if (targeting1.get('age_min') == targeting2.get('age_min') and targeting1.get('geo_locations') == targeting2.get('geo_locations')): overlaps.append({ 'adset1': adset1['name'], 'adset2': adset2['name'], 'estimated_overlap': 0.25 # Would calculate with real data }) for overlap in overlaps: if overlap['estimated_overlap'] > 0.20: print(f"High overlap detected: {overlap['adset1']} <-> {overlap['adset2']}") EOF

Workflow 04

Performance Anomaly Detection

Monitors key metrics every hour and alerts when performance deviates significantly from historical baselines. Catches issues like disapproved ads, bid cap problems, or audience saturation before they waste significant budget.

# Anomaly detection (runs hourly) # Get last hour's performance meta ads insights get \ --level campaign \ --time-range '{"since":"'$(date -d '1 hour ago' +%Y-%m-%d)'","until":"'$(date +%Y-%m-%d)'"}' \ --fields campaign_id,campaign_name,spend,cpm,ctr,conversions \ --format json > current_hour.json # Compare against 30-day baseline meta ads insights get \ --level campaign \ --date-preset last_30d \ --fields campaign_id,cpm,ctr \ --format json > baseline.json # Python script for statistical analysis python detect_anomalies.py current_hour.json baseline.json # If anomalies detected, send Slack alert if [ $? -eq 1 ]; then curl -X POST -H 'Content-type: application/json' \ --data '{"text":"🚨 Meta Ads anomaly detected. Check dashboard."}' \ $SLACK_WEBHOOK_URL fi

Sarah K.

Senior Performance Engineer

AdTech Startup

★★★★★

“

Meta CLI replaced 15 hours of manual campaign management per week with automated scripts. Our AI agents now handle budget rebalancing, creative rotation, and anomaly detection. CPAs dropped 34% since implementing systematic automation.”

34%

CPA reduction

15 hrs

Weekly saved

100%

Automated

Should you use Meta CLI or Meta MCP for automation?

Meta released both the Meta CLI and Meta MCP (Model Context Protocol) simultaneously in April 2026. Both connect to the same Marketing API, but they serve different automation philosophies. The choice depends on whether you want terminal-based scripting or conversational AI interfaces. For a detailed MCP guide, see How to Connect Claude to Meta Ads via MCP.

Feature	Meta CLI	Meta MCP
Interface	Command line terminal	Chat with Claude/ChatGPT
Setup complexity	Medium (Python + tokens)	Low (OAuth in browser)
Automation style	Scripts, cron jobs, CI/CD	Natural language prompts
Data processing	JSON, CSV, pipes to other tools	AI analysis and interpretation
Best for	Developers, DevOps, systematic automation	Marketers, ad hoc analysis, exploration
Learning curve	Steep (command syntax)	Gentle (plain English)

Use Meta CLI when: You need scheduled automation (daily budget rebalancing, hourly monitoring), complex data processing (statistical analysis, custom algorithms), integration with existing DevOps workflows, or deterministic behavior for production systems.

Use Meta MCP when: You want conversational analysis ("Why did CPMs spike yesterday?"), quick exploration of account data, one-time reporting tasks, or you prefer natural language over command syntax.

Many teams use both approaches: Meta MCP for exploration and analysis, Meta CLI for production automation. The tools complement each other rather than compete. For teams wanting fully autonomous optimization without manual scripting, Ryze AI handles the entire workflow — monitoring, analysis, and execution — with built-in guardrails and performance guarantees.

Frequently asked questions

Q: Is Meta CLI free to use?

Yes, Meta CLI is free software. You only pay for the ad spend managed through the tool. The CLI requires Python 3.12+ and Meta Marketing API access, but there are no additional licensing fees from Meta.

Q: What Python version does Meta CLI require?

Meta CLI requires Python 3.12 or higher. This is because it uses modern Python features like improved error messages and performance optimizations. Install the latest Python from python.org if your system runs an older version.

Q: Can Meta CLI create campaigns automatically?

Yes. Use meta ads campaign create with parameters for name, objective, budget, and targeting. New campaigns default to PAUSED status for safety — you must manually activate them or use --status ACTIVE in your automation scripts.

Q: How do I handle Meta API rate limits in automation?

Meta CLI respects API rate limits automatically and returns exit code 4 when limits are hit. In scripts, implement exponential backoff: wait 1 second, retry; if it fails again, wait 2 seconds, retry; continue doubling the wait time.

Q: What's the difference between Meta CLI and third-party tools?

Meta CLI is the official tool from Meta with guaranteed API compatibility and ongoing support. Third-party tools may have more features but risk breaking when Meta updates the API. The CLI provides the most stable foundation for automation.

Q: Can I use Meta CLI without programming skills?

Meta CLI requires basic command-line comfort. Non-programmers often find Meta MCP (with Claude or ChatGPT) more accessible since it uses natural language. For fully automated management without technical setup, Ryze AI provides a complete solution.