meta-ads-cli

# Meta Ads CLI Agent Skill This skill teaches an AI agent to operate Meta ads through Meta's official **Ads CLI** instead of reimplementing the Marketing API. The core command shape is: ```bash meta ads <resource> <action> [options] ``` Examples from the official Ads CLI pattern include: ```bash meta ads campaign list meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000 meta ads adset create CAMPAIGN_ID --name "My Ad Set" --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS --targeting-countries US meta ads creative create --name "Hero Banner" --page-id 111222333 --image ./banner.jpg --body "50% off" --title "Shop Now" --link-url https://example.com/sale --call-to-action SHOP_NOW meta ads ad create ADSET_ID --name "Hero Banner Ad" --creative-id CREATIVE_ID meta ads insights get --campaign_id CAMPAIGN_ID --fields impressions,conversions,spend --date-preset last_7d ``` Use the bundled guard script as the default execution path: ```bash python3 scripts/meta_ads_agent.py doctor python3 scripts/meta_ads_agent.py classify -- meta ads campaign list python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25 ``` The guard script does **not** replace Meta's CLI. It wraps it so agents behave safely and consistently. ## Highest-priority rules 1. **Use Meta's official CLI first.** Do not call Graph API directly unless the official CLI cannot do the task and the user explicitly accepts a lower-level workaround. 2. **Read before write.** Inspect the relevant account/object/performance state before changing it. 3. **No spend-affecting change without explicit user approval.** Writes, budget changes, activation, delete/remove, dataset/catalog connections, and creative uploads need approval. 4. **Never activate by accident.** New objects should remain `PAUSED` unless the user explicitly asks to activate. `ACTIVE`, `activate`, `delete`, `remove`, and `--force` are high-risk. 5. **Prefer machine-readable output.** Use JSON whenever possible: `meta --output json ads ...`. Use table output only for human presentation. 6. **One write step at a time.** Apply one mutation, verify it, then continue. 7. **Do not invent IDs.** Resolve account, campaign, ad set, creative, page, pixel/dataset, catalog, product set, and targeting IDs from the CLI or user-provided values. 8. **Keep tokens out of chat and logs.** Never print access tokens, app secrets, cookies, or `.env` contents. 9. **Ask for missing material only when blocking.** For reads, proceed with defaults. For writes, collect exact account, IDs, budget, date range, page/dataset/catalog, destination URL, and approval. 10. **Treat regulated/special categories carefully.** Housing, employment, credit, politics, social issues, health, financial services, minors, and sensitive audiences require extra review and conservative targeting. ## Recommended agent flow For almost every request, follow this order: ```text 1. Classify request: read-only, ordinary write, budget/write, activation, destructive, regulated. 2. Run doctor/auth check if account access is uncertain. 3. Read current state with compact JSON output. 4. Produce a short plan with exact commands, risks, assumptions, and verification commands. 5. For read-only tasks: run commands and summarise. 6. For writes: wait for explicit approval, then run through scripts/meta_ads_agent.py. 7. Verify state after every write. 8. Report what changed, object IDs, before/after values, and any unresolved issues. ``` ## Install and auth checklist ```bash # Meta docs list meta-ads as the package name. python3.12 -m pip install meta-ads # Confirm the CLI is available. meta --help meta ads --help # Auth status. Meta docs show ACCESS_TOKEN for token-based auth. export ACCESS_TOKEN=<ACCESS_TOKEN> meta auth status # Prefer an explicit ad account for every command until a default is proven. meta ads --ad-account-id <AD_ACCOUNT_ID> campaign list ``` Do not guess config keys if auth fails. Run: ```bash meta auth status meta ads --help meta ads <resource> --help ``` Then follow the official CLI setup/configuration docs for the installed version. ## Using the guard script ### Check readiness ```bash python3 scripts/meta_ads_agent.py doctor ``` ### Classify command risk without executing ```bash python3 scripts/meta_ads_agent.py classify -- meta ads campaign update 123 --status ACTIVE ``` ### Run a read-only command ```bash python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25 ``` ### Run a write after approval ```bash python3 scripts/meta_ads_agent.py run \ --approved "User approved creating the paused campaign named Summer Sale in account act_123" \ -- meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000 ``` ### Run an activation after stronger approval ```bash python3 scripts/meta_ads_agent.py run \ --approved "User approved activating campaign 123 after reviewing it" \ --allow-active \ -- meta ads campaign update 123 --status ACTIVE ``` ### Lint or run a multi-step plan ```bash python3 scripts/meta_ads_agent.py lint-plan templates/weekly-report-plan.json python3 scripts/meta_ads_agent.py run-plan templates/weekly-report-plan.json ``` Write-heavy plans require `--approved ...`; activation/destructive plans require additional flags. ## Fast task routing | User intent | First action | Main workflow | |---|---|---| | “Show performance” | Read-only | `references/REPORTING.md` | | “What should I pause?” | Read insights, then propose | `references/WORKFLOWS.md#performance-triage` | | “Pause this ad/campaign” | Read object + metrics | `references/WORKFLOWS.md#safe-pause` | | “Increase budget” | Read currency, current budget, delivery | `references/WORKFLOWS.md#budget-change` | | “Launch campaign” | Build paused launch plan | `references/WORKFLOWS.md#paused-launch` | | “Create catalogue/product set” | Check account/catalog context | `references/WORKFLOWS.md#catalogs-and-products` | | “Check pixel” | Dataset and insights audit | `references/WORKFLOWS.md#datasetpixel-audit` | | “Use another endpoint” | Verify official CLI coverage first | `references/TROUBLESHOOTING.md#when-the-cli-does-not-cover-the-task` | ## Output expectations For read-only analysis, return: ```text - what was queried - date range and attribution assumptions - top findings with numbers - caveats about missing/zero/odd metrics - recommended next actions separated from actual changes ``` For writes, return: ```text - object IDs touched - before/after values - command(s) run, redacted where needed - verification result - anything still paused/not live - any follow-up the user must perform in Ads Manager ``` ## References in this skill - `references/CRITICAL-ANALYSIS-v1.md` — what v1 got right/wrong and why v2 changed direction. - `references/OFFICIAL-ADS-CLI.md` — concise Ads CLI reference for agents. - `references/AGENT-OPERATING-MODEL.md` — how agents should reason, plan, execute, and recover. - `references/SAFETY.md` — approval gates, budget/activation/destructive rules. - `references/WORKFLOWS.md` — account audits, reporting, launch, pause, budget, dataset/catalog workflows. - `references/REPORTING.md` — Insights fields, date ranges, breakdowns, and interpretation. - `references/COMMANDS.md` — command patterns and help-discovery strategy. - `references/OPTIMISATION-DECISIONING.md` — how to turn metrics into cautious recommendations. - `resources/command-catalog.json` and `resources/risk-rules.json` — machine-readable aids for agents. - `agent-prompts/` and `AGENTS.md` — ready-made prompts/instructions for general shell agents. - `references/TROUBLESHOOTING.md` — auth, exit codes, output parsing, rate limits, API errors. - `references/PORTABILITY.md` — using this skill in non-OpenClaw agents. - `templates/` — JSON plan templates and schema. - `scripts/meta_ads_agent.py` — optional safe command runner. - `evals/` — behavioural evals for agent skill quality.