Jonathon's AI Wiki

Meta Ads CLI — Command-Line Interface for Meta Ads and Commerce

6 min read

Source: X Bookmark 2049645369760592101 (Matt Berman tweet → @Meta announcement) → Meta Ads Cli 2026 05 02 (Meta Developers blog, full content extracted)

Meta launched the Ads CLI on April 29, 2026 — the official command-line interface for the Meta Marketing API. It packages campaign / adset / ad / creative / insights / catalog / dataset operations into predictable shell commands that work for both human developers and AI agents. The pitch: stop writing custom auth/pagination/output-formatting code for the Marketing API; use one tool with table / json / plain output formats and standard exit codes for CI/CD pipelines.

Key Takeaways

  • Targeted at agents, not just humans. From the Meta announcement: “Developers and AI agents working with the Meta Marketing API can now create, edit, and analyze campaigns directly from the command line, without writing custom code.” Meta explicitly designed the command surface for predictable AI-agent invocation.
  • Resources created in PAUSED status by default. Nothing goes live until you flip status to ACTIVE. Critical safety affordance for AI-agent use: a model can stage a full campaign without risk of accidentally spending money.
  • Three output formats: table (human), json (pipe to jq), plain (tab-separated for sort / awk / cut).
  • Standard exit codes: 0 success, 3 auth error, 4 API error, etc. Reliable shell error handling.
  • --no-input and --force suppress prompts for unattended runs.
  • Environment-variable secrets. Tokens and account IDs come from env vars, keeping them out of command history and version control.
  • Python 3.12+ with pip or uv.
  • Coverage: Campaigns, adsets, ads, creatives, insights, catalogs, products, product sets, datasets (conversion pixels). Full lifecycle from “create paused campaign” through “go live” through “query last-7-day insights” to “wire a conversion pixel to an ad account.”

Why this is a step-change for paid-ads automation

Before the CLI:

  • Every team built its own thin wrapper over the Marketing API.
  • Auth flow, pagination, retry handling, output normalization — each team wrote it again.
  • AI-agent integration meant the agent had to know the raw Graph API endpoints (or call your custom wrapper).

After the CLI:

  • Both your AI agent and your CI/CD pipeline call the same meta ads ... commands.
  • The agent’s “vocabulary” is the CLI’s command structure — discoverable via --help, predictable, well-documented.
  • A Claude Code skill / Codex session / generic LLM-orchestrator can drive Meta Ads operations without you exposing your custom wrapper to it.

The shape mirrors what Railway shipped for deployment infrastructure: an official, agent-aware tool surface from the platform vendor itself, removing the “everyone builds the wrapper” tax.

Concrete examples

# Create a paused $50/day campaign
meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000
 
# Adset
meta ads adset create CAMPAIGN_ID --name "My Ad Set" \
  --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS \
  --bid-amount 500 --targeting-countries US
 
# Creative
meta ads creative create --name "Hero Banner" --page-id 111222333 --image ./banner.jpg \
  --body "50% off everything!" --title "Shop Now" \
  --link-url https://example.com/sale --call-to-action SHOP_NOW
 
# Wire it together
meta ads ad create ADSET_ID --name "Hero Banner Ad" --creative-id CREATIVE_ID
 
# Go live (now nothing was at risk before this point)
meta ads campaign update CAMPAIGN_ID --status ACTIVE
meta ads adset update ADSET_ID --status ACTIVE
meta ads ad update AD_ID --status ACTIVE
 
# Pull last-7-day insights as JSON
meta ads insights get --campaign_id CAMPAIGN_ID --fields=impressions,conversions --date-preset last_7d --output json
 
# Catalog ops
meta ads catalog create --name "My Catalog"
meta ads product-item create --catalog-id 123456 \
  --retailer-id sku_a --name "Blue Shirt" --price "999" --currency "USD" \
  --image-url https://example.com/blue_shirt.jpg
 
# Dataset (conversion pixel)
meta ads dataset create --name "Website Pixel"
meta ads dataset connect 111222 --ad-account-id 333444 --catalog-id 555666

Implementation

Tool/Service: Meta Ads CLI (meta ads) Setup:

# Python 3.12+ required
pip install meta-ads-cli  # or uv equivalent
# Configure tokens via env vars (specifics in official docs)
export META_ACCESS_TOKEN=...
export META_AD_ACCOUNT_ID=...

Cost: Free CLI; you still pay for the underlying ad spend and Marketing API usage as before. Integration notes:

  • For AI-agent use, give the agent permission to run meta ads ... --output json and parse the JSON. The PAUSED-by-default behavior plus the explicit update --status ACTIVE step gives you a clean two-step “stage then approve” pattern an agent can follow.
  • For CI/CD, lean on --no-input --force plus --output plain for shell-friendly piping. Standard exit codes mean a single set -e is enough for fail-fast pipelines.
  • Pair with Outcome Kit for outcome-attribution if you’re building agent-driven optimization loops.

Why this matters for WEO Marketly

WEO Marketly runs paid-ads campaigns for clients on Meta. Before the CLI, every campaign-launch script lived in custom code that called Graph API endpoints directly — fragile, duplicated across clients, and not easily delegated to an AI agent. After the CLI:

  • A Claude Code skill can stage and review a full campaign (paused) before a human approves a single meta ads campaign update --status ACTIVE.
  • Insights pulls become a one-line meta ads insights get ... --output json that can be piped into a weekly report agent (compare to Clawdbot’s pattern for SEO).
  • Conversion pixels and catalog pipelines become scriptable for the dental clients (DTC product catalogs are less common than service-based catalogs, but the dataset-pixel flow applies cleanly to local-services advertisers).

Try It

  1. Install the CLI in a Python 3.12+ environment: read the official docs at https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-cli/ads-cli-overview.
  2. Stage a paused test campaign for a fictional client (use Smile Springs Family Dental — the canonical fictional client used throughout the Intermediate Course) and confirm it appears in the Meta Ads Manager UI.
  3. Pull insights with --output json | jq to confirm the JSON shape works for your reporting pipeline.
  4. Spike a Claude Code skill that wraps meta ads campaign create + meta ads adset create + meta ads creative create into a single “stage a paused campaign from a brief” command. Keep the final “go live” step manual.

Open Questions

  • OAuth flow for multi-client agencies. WEO needs to act on behalf of multiple ad accounts; how does the CLI handle multi-account token rotation? Likely covered in the docs but not in the announcement post.
  • Rate limits. The Marketing API has aggressive rate limits; does the CLI add retry/backoff or expose that to the caller?
  • Sandbox accounts. The announcement doesn’t mention test/sandbox account support — important for safe agent dev.
  • MCP server in the future? The CLI is the first piece. A Remote MCP server (like Railway’s) seems like a natural follow-up for editor-native agent use.

Cross-link note: This article is the first wiki entry on Meta Ads tooling specifically (vs. paid-ads strategy, which is covered by the paid-ads skill). Future Meta-side ingests should land here or in a sibling article.

Graph View

Backlinks