Back to Details

meta-ads-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Meta Ads CLI Agent Skill

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.
本Skill用于指导AI Agent通过Meta官方Ads CLI操作Meta广告，而非重新实现Marketing API。
核心命令格式为：
bash
meta ads <resource> <action> [options]
官方Ads CLI模式的示例包括：
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
使用捆绑的防护脚本作为默认执行路径：
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
防护脚本不会替代Meta的CLI，它只是对其进行封装，确保Agent的操作安全且一致。

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.
  1. 优先使用Meta官方CLI。除非官方CLI无法完成任务且用户明确接受低级别替代方案，否则不要直接调用Graph API。
  2. 写前读。在进行更改前，先检查相关账户/对象/性能状态。
  3. 涉及支出的更改需明确用户批准。写入操作、预算变更、激活、删除/移除、数据集/目录关联以及创意上传都需要获得批准。
  4. 避免意外激活。新创建的对象应保持
    PAUSED
    状态，除非用户明确要求激活。
    ACTIVE
    、
    activate
    、
    delete
    、
    remove
    和
    --force
    属于高风险操作。
  5. 优先选择机器可读输出。尽可能使用JSON格式：
    meta --output json ads ...
    。仅在面向人类展示时使用表格输出。
  6. 一次执行一个写入步骤。执行一次变更，验证其有效性，再继续下一步。
  7. 不要自行生成ID。从CLI或用户提供的值中解析账户、广告系列、广告组、创意、主页、像素/数据集、目录、产品集和定向ID。
  8. 不要在聊天和日志中泄露令牌。绝不要打印访问令牌、应用密钥、Cookie或
    .env
    文件内容。
  9. 仅在阻塞时询问缺失信息。对于读取操作，使用默认值继续。对于写入操作，收集确切的账户、ID、预算、日期范围、主页/数据集/目录、目标URL以及用户批准。
  10. 谨慎处理受监管/特殊类别。住房、就业、信贷、政治、社会议题、健康、金融服务、未成年人和敏感受众相关的广告需要额外审核和保守的定向策略。

Recommended agent flow

推荐的Agent工作流

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.
几乎所有请求都应遵循以下顺序：
text
1. 分类请求：只读、普通写入、预算/写入、激活、破坏性操作、受监管操作。
2. 如果账户访问权限不确定，运行doctor/auth检查。
3. 使用紧凑的JSON输出读取当前状态。
4. 生成包含确切命令、风险、假设和验证命令的简短计划。
5. 对于只读任务：运行命令并总结结果。
6. 对于写入任务：等待明确批准，然后通过scripts/meta_ads_agent.py执行。
7. 每次写入后验证状态。
8. 报告变更内容、对象ID、变更前后的值以及任何未解决的问题。

Install and auth checklist

安装与认证检查清单

bash
undefined
bash
undefined

Meta docs list meta-ads as the package name.

Meta文档中列出的包名为meta-ads。

python3.12 -m pip install meta-ads
python3.12 -m pip install meta-ads

Confirm the CLI is available.

确认CLI可用。

meta --help meta ads --help
meta --help meta ads --help

Auth status. Meta docs show ACCESS_TOKEN for token-based auth.

认证状态。Meta文档显示使用ACCESS_TOKEN进行基于令牌的认证。

export ACCESS_TOKEN=<ACCESS_TOKEN> meta auth status
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.
meta ads --ad-account-id <AD_ACCOUNT_ID> campaign list

如果认证失败，不要猜测配置密钥。运行以下命令：

```bash
meta auth status
meta ads --help
meta ads <resource> --help
然后遵循已安装版本的官方CLI设置/配置文档。

Using the guard script

使用防护脚本

Check readiness

检查就绪状态

bash
python3 scripts/meta_ads_agent.py doctor
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
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
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
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
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.
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
写入密集型计划需要
--approved ...
参数；激活/破坏性计划需要额外的标志。

Fast task routing

快速任务路由

User intentFirst actionMain 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
用户意图首要操作主要工作流
“展示广告效果”只读操作
references/REPORTING.md
“我应该暂停哪些广告？”读取洞察数据，然后提出建议
references/WORKFLOWS.md#performance-triage
“暂停此广告/广告系列”读取对象+指标
references/WORKFLOWS.md#safe-pause
“增加预算”读取货币类型、当前预算、投放情况
references/WORKFLOWS.md#budget-change
“启动广告系列”构建默认暂停的启动计划
references/WORKFLOWS.md#paused-launch
“创建商品目录/产品集”检查账户/目录上下文
references/WORKFLOWS.md#catalogs-and-products
“检查像素”数据集和洞察审计
references/WORKFLOWS.md#datasetpixel-audit
“使用其他端点”先验证官方CLI是否支持
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
对于只读分析，返回内容应包括：
text
- 查询内容
- 日期范围和归因假设
- 带数值的关键发现
- 关于缺失/零值/异常指标的说明
- 建议的后续操作（与实际变更分开）
对于写入操作，返回内容应包括：
text
- 涉及的对象ID
- 变更前后的值
- 执行的命令（必要时脱敏）
- 验证结果
- 仍处于暂停/未上线状态的内容
- 用户必须在Ads Manager中执行的后续操作

References in this skill

本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.
  • references/CRITICAL-ANALYSIS-v1.md
    — v1版本的优缺点，以及v2版本调整方向的原因。
  • references/OFFICIAL-ADS-CLI.md
    — 供Agent使用的简洁Ads CLI参考文档。
  • references/AGENT-OPERATING-MODEL.md
    — Agent应如何推理、规划、执行和恢复。
  • references/SAFETY.md
    — 批准机制、预算/激活/破坏性操作规则。
  • references/WORKFLOWS.md
    — 账户审计、报告、启动、暂停、预算、数据集/目录工作流。
  • references/REPORTING.md
    — 洞察字段、日期范围、细分维度及解读方式。
  • references/COMMANDS.md
    — 命令模式和帮助发现策略。
  • references/OPTIMISATION-DECISIONING.md
    — 如何将指标转化为谨慎的建议。
  • resources/command-catalog.json
    和 
    resources/risk-rules.json
    — 供Agent使用的机器可读辅助工具。
  • agent-prompts/
    和 
    AGENTS.md
    — 为通用Shell Agent准备的提示词/说明文档。
  • references/TROUBLESHOOTING.md
    — 认证、退出码、输出解析、速率限制、API错误排查。
  • references/PORTABILITY.md
    — 在非OpenClaw Agent中使用本Skill的方法。
  • templates/
    — JSON计划模板和 schema。
  • scripts/meta_ads_agent.py
    — 可选的安全命令运行器。
  • evals/
    — 用于评估Agent Skill质量的行为评估工具。