Meta Ads (Facebook + Instagram) · terminal-driven
Meta Ads CLI — Run Meta Ads from Claude Code
Meta shipped an official terminal CLI on April 29, 2026 — the same 29 tools as the MCP, callable from any Claude Code or scripted workflow. Here's how to install it, where it fits, and how to extend it with GoMarble's hosted MCP for cross-platform work.
Used by paid media teams at
$ npm install -g @meta/ads-cli
+ @meta/ads-cli@1.0.0-beta
added 47 packages in 6s
$ meta-ads-cli auth login
→ Opening Meta Business OAuth in browser...
✓ Signed in as adityasriram@gomarble.ai
✓ 3 ad accounts connected
$ claude
> Use Meta Ads CLI. Pause any creative with frequency >4
and CTR drop >20% week-over-week. Show me what you paused.
⏳ Fetching insights from account act_***6204...
⏳ Comparing last 7 days to previous 7 days...
✓ Identified 8 creatives matching criteria
✓ Paused 8 ads in account act_***6204
PAUSED:
• Glycerin 23 / Plush Premium V3 — freq 4.8, CTR -32% WoW
• Ghost 18 / Daily Miles V1 — freq 4.2, CTR -28% WoW
• Trail / New Ghost V2 — freq 4.4, CTR -24% WoW
• +5 more (full list saved to ./paused-2026-05-23.csv)
> ▌Real prompt structure. Anonymized account ID. Thresholds from the workflows below.
What is the Meta Ads CLI?
The Meta Ads MCP and Meta Ads CLI expose the same 29 tools and the same Marketing API surface. The MCP is built for conversational use inside Claude/ChatGPT/Cursor. The CLI is built for the terminal — and that's where Claude Code already lives. If you spend your day in a terminal, the CLI integrates more naturally with the rest of your shell workflows.
Setup with Claude Code
- Install the CLI globally: `npm install -g @meta/ads-cli`
- Run `meta-ads-cli auth login` and complete the Facebook Business OAuth flow
- Verify access: `meta-ads-cli accounts list` — should print your ad accounts
- In Claude Code, prompt Claude to use the CLI: `claude 'Use Meta Ads CLI to ...'`
6 workflows to try
Copy any of these into Claude Code. The CLI does the API calls; Claude parses the results and continues the conversation. Each card includes the equivalent click-path in Ads Manager UI for honest comparison.
Daily performance brief
Prompt to Claude
Show me ROAS by campaign for the last 7 days. Flag any campaign with >$1K spend and ROAS below 1.5x.
Terminal command
claude 'Use the Meta Ads CLI to pull last 7 days of campaign performance for account act_XXXX. List ROAS per campaign. Flag campaigns with >$1K spend and ROAS below 1.5x.'What happens: Claude Code invokes the CLI's reporting tools, parses results, and prints a structured table — no UI clicks.
Replaces: Ads Manager: open account → Campaigns tab → set date range → toggle columns → sort by ROAS → manually filter spend column. ~3-5 minutes per check.
Pause underperforming creatives
Prompt to Claude
Find any creative with frequency >4 AND CTR drop >20% week-over-week, then pause it.
Terminal command
claude 'Use Meta Ads CLI. For account act_XXXX, find creatives with frequency >4 and CTR declining >20% WoW. Pause them. Show me what you paused.'What happens: Read tools identify candidates; write tools execute the pause; Claude prints the diff before-after.
Replaces: Ads Manager: ~15 clicks per creative (find ad → check frequency → check CTR change → toggle off). For 12 fatigued creatives that's ~180 clicks and ~30 minutes.
Catalog feed health check
Prompt to Claude
Audit my product catalog feed and report broken images, missing fields, and rejected products.
Terminal command
claude 'Use Meta Ads CLI. Run a catalog diagnostics check on my primary catalog. Group issues by severity. Show me the top 5 product errors.'What happens: Catalog operations tools surface feed rules, diagnostics, and rejected products — same data the Commerce Manager UI shows but as a structured summary.
Replaces: Commerce Manager: navigate to Catalog → Issues tab → expand each error type → export to CSV → manually triage. ~20-30 minutes.
Audience overlap detection
Prompt to Claude
Find ad sets in my account that are competing for the same audience. Group by overlap severity.
Terminal command
claude 'Use Meta Ads CLI. For account act_XXXX, identify ad sets with audience overlap >25%. Show me which campaigns are cannibalizing each other.'What happens: Account diagnostics tools surface audience overlap and auction competition data — surfaces the cannibalization Ads Manager hides 5 menus deep.
Replaces: Ads Manager: Audience Insights → Audience Overlap tool → manually pick ad sets to compare in pairs. To check 10 ad sets means 45 pairwise comparisons. ~45 minutes if you're patient.
Learning phase diagnostics
Prompt to Claude
Show me every ad set currently stuck in learning phase. Tell me what's blocking each one and how to fix it.
Terminal command
claude 'Use Meta Ads CLI. List ad sets in learning_limited or learning state. For each, identify the cause (budget, audience size, conversion volume) and recommend the smallest change to exit learning.'What happens: Diagnostics tools surface learning phase status + reasons. Claude reads Meta's official guidance and proposes fixes per ad set.
Replaces: Ads Manager: filter campaigns by delivery status → click each ad set → check delivery info → look up what 'Learning Limited' means in Meta help docs. ~5 min per ad set; many marketers never check.
Daily Slack performance summary
Prompt to Claude
Generate a 1-paragraph performance summary for yesterday I can paste into Slack. Include spend, ROAS, top winner, top loser.
Terminal command
claude 'Use Meta Ads CLI. Pull yesterday's account-level metrics for act_XXXX. Write a 4-sentence Slack-ready summary: total spend, blended ROAS, name of best-performing ad set, name of worst. Include % change vs the previous day.'What happens: Reporting tools pull the metrics; Claude formats a copy-pasteable summary. Runs in <30 seconds.
Replaces: Ads Manager + scratch pad: pull yesterday's numbers, compare to day-before in your head, type up a summary, edit for tone. ~10-15 minutes most teams skip.
Try every workflow above on your own account.
GoMarble's hosted MCP works with these prompts the same way — plus Google, TikTok, Shopify, and Klaviyo in the same Claude session.
Time savings vs Ads Manager UI
Meta's official CLI lets Claude Code automate the click-heavy parts of Ads Manager. Below: real before/after times based on actual Ads Manager workflows — no fabricated metrics.
| Task | Ads Manager UI | CLI / Claude Code |
|---|---|---|
| Pause 12 fatiguing creatives | ~30 min (~180 clicks) | <1 min (one prompt) |
| Audit catalog feed for product errors | ~25 min | <1 min |
| Find audience overlap across 10 ad sets | ~45 min (45 pairwise comparisons) | <1 min |
| Diagnose 8 ad sets stuck in learning | ~40 min | ~2 min |
| Daily Slack performance summary | ~12 min | ~30 seconds |
These aren't agency-grade ROAS claims — they're click-counted estimates of how long the same task takes in Ads Manager's UI vs one Claude prompt against the CLI. Your mileage varies with account complexity.
Troubleshooting common errors
Meta Ads CLI is in beta, and Meta's API quotas + OAuth scopes catch most teams in the first week. Here are the issues that come up most.
OAuth login fails — "Invalid OAuth scope"
Symptom
Running `meta-ads-cli auth login` opens the browser but the callback errors with "Invalid scope" or returns to terminal with no token.
Fix
You need ads_management permission on the Meta Business account. Visit business.facebook.com → Settings → People → confirm your user has "Manage Campaigns" or higher. If you're a developer, the CLI uses your default Business Manager identity, not your developer app credentials. Re-run `meta-ads-cli auth login` after permissions are granted.
"ENOTFOUND mcp.facebook.com" or hostname resolution failure
Symptom
Network error when the CLI tries to authenticate.
Fix
Two common causes: (1) corporate DNS / VPN blocking facebook.com endpoints — try outside corp network or whitelist `*.facebook.com`. (2) Open beta access not yet provisioned on your Business account — open a Meta Business Help case to confirm beta access. Open beta as of April 29, 2026 is rolling out gradually.
Rate limit errors (HTTP 429)
Symptom
CLI fails partway through a multi-tool prompt with "Too many requests" or `application_request_limit_reached`.
Fix
Meta's Marketing API uses per-user and per-ad-account quotas. Common triggers: pulling insights for a large account in tight loops, or running multiple prompts concurrently. Mitigations: (1) reduce limit/batch size in your prompt, (2) wait the documented backoff window (usually 60-300 seconds), (3) use the CLI's built-in retry flag if available. For high-frequency reads, GoMarble's hosted MCP batches calls server-side and respects quota more gracefully.
Token expires or stops working after 60 days
Symptom
CLI returns 401 unauthorized after weeks of working fine.
Fix
Meta Business OAuth tokens have a refresh policy tied to your Business session. Re-run `meta-ads-cli auth login` to refresh. If your Business identity has changed (new role, new MFA enrollment), you may need to revoke the old token in Business Settings → Business Integrations → revoke "Meta Ads CLI" → re-authorize.
Write operations fail with "Insufficient role permissions"
Symptom
Read tools work fine, but pause/budget-change/create-campaign actions error out.
Fix
Meta requires "Manage Campaigns" permission for any write op, even if you have ads_read. Confirm your Business role in Business Settings → People → click your name → review per-account permissions. Common gotcha: agency accounts often grant "Ads Manager" (read-only-like) instead of "Manage Campaigns". Get the client to upgrade your role.
CLI updates break a prompt that worked yesterday
Symptom
Tool name or output format changed between CLI versions, breaking a previously-working Claude prompt.
Fix
Meta's CLI is in open beta (released April 29, 2026), so tool surface may change. Two stabilization options: (1) pin the version with `npm install -g @meta/ads-cli@<version>`, (2) re-frame prompts in semantic terms ("pull last 7 days' campaign performance") rather than tool names. Semantic prompts survive CLI updates better.
Where the CLI stops — and GoMarble extends
Add GoMarble's hosted MCP to your Claude Code session alongside Meta's CLI. Claude routes Meta-specific calls to Meta's CLI and cross-platform / competitor / Shopify calls to GoMarble. Both run in the same prompt.
What the Meta Ads CLI can't do
- —Meta-only — no Google Ads, TikTok, LinkedIn, or Bing context
- —No competitor research — can't see what other brands are running
- —No Shopify or Klaviyo revenue reconciliation
- —No GA4 / Search Console for traffic-side data
Add GoMarble's hosted MCP
- Sign up at apps.gomarble.ai/users/sign-up
- Connect Meta + Google + Shopify in Integrations
- Open claude.ai/settings/integrations
- Add Custom Connector — URL: https://apps.gomarble.ai/mcp-api/sse
- In Claude Code, both tools are now available
https://apps.gomarble.ai/mcp-api/sseCombined sample prompt
Pull Meta and Google ad performance from last 14 days. Identify the underperforming Meta campaigns (use Meta CLI), then cross-reference with Shopify to see actual revenue. Generate a one-pager.
Which option, when?
| Option | Use when | Limits |
|---|---|---|
| Meta Ads CLI alone | You only run Meta ads, work in the terminal, and want zero ongoing cost | Meta-only; no competitor research; no cross-channel data |
| Meta Ads CLI + GoMarble MCP | You run Meta + other platforms and want everything in Claude Code's terminal | Two tools to maintain (negligible overhead since both are stable) |
| GoMarble Platform only | You want scheduled jobs, dashboards, Agent Mode, and non-technical teammate access | Less terminal-native than the CLI |
“This AI Agent replaces a senior data analyst with an average salary of $130K/year.”
“GoMarble is basically creative intelligence on autopilot.”
“This is a no-brainer and something my team is now using daily.”
Frequently asked
What is the Meta Ads CLI?
Is the Meta Ads CLI free?
Can I use it inside Claude Code?
Does the Meta Ads CLI work with Google Ads, TikTok, or LinkedIn?
Can the CLI make changes (pause campaigns, adjust budgets)?
What's the difference vs Meta's MCP server?
Related reading
Meta Ads MCP — Official vs GoMarble
Same 29 tools, conversational transport instead of CLI.
Meta Ads AI Connectors — Explainer
What the umbrella product actually includes.
Creative Fatigue Detection — Use Case
Lead-magnet prompt that uses the same Meta Marketing API surface.
Madgicx Alternatives
If you're evaluating Meta automation platforms alongside the CLI.
Run all your paid media from one terminal session.
GoMarble's hosted MCP gives Claude Code access to Meta + every other ad platform + Shopify + Klaviyo + GA4 + competitor research in one connection.
Sources: Meta Just Shipped an Ads CLI for AI Agents — Humblytics · Meta Ads CLI with Claude Code: Complete 2026 Setup Guide · Meta CLI — Command-Line Tool for Meta Ads Automation 2026