Translate prompts into explicit engine commands.

Plain-English prompts that work. The agent translates these into the right CLI commands.

Performance & reporting

• "Show me my Meta ad spend by campaign for the last 7 days"
• "Run this GAQL query against Google Ads"
• "What's my TikTok campaign performance this month?"
• "What did my Pinterest campaigns spend last week?"
• "Show me LinkedIn campaign performance for this month"
• "Show me X campaign engagement for the last 7 days"
• "Pull a daily breakdown of impressions and clicks across all campaigns"
• "Export last week's Meta performance report to CSV"
• "Run an async report for all my TikTok ads since January"
• "Submit a Pinterest report run and wait for the result URL"

Accounts & campaigns

• "What businesses do I have access to in Meta?"
• "List all my accessible Google Ads customers"
• "List all my TikTok advertisers"
• "List my Pinterest ad accounts"
• "List my LinkedIn ad accounts"
• "List my X ads accounts"
• "Show me the campaigns in my Meta ad account"
• "Which ad sets are running right now?"

Creative & tracking

• "Show my TikTok video creatives"
• "Check if my Meta pixel is working"
• "Find broken pixels across my Meta accounts"
• "What audiences do I have in TikTok?"
• "What audiences do I have in Pinterest?"
• "What custom audiences do I have in X?"

Setup & troubleshooting

• "Show me which providers are already authenticated"
• "Help me set up my Meta auth token"
• "Is my TikTok token still valid?"
• "Refresh my Pinterest token"
• "Run a doctor check on my account"
• "My token expired — how do I refresh it?"

Translating marketer language to CLI concepts:

Every command starts with agent-ads <provider>. This is intentional — each ad platform has different APIs, auth, object models, and semantics, so the CLI keeps them separate rather than papering over differences.

• Canonical: agent-ads meta insights query ...
• Never: agent-ads insights query ... (no implicit provider)
• Never: agent-ads meta:insights:query (no colon syntax)

Check live: agent-ads providers list

For a cross-provider auth summary or guided local setup, use agent-ads auth.

Each routing guide tells you which specific reference file to load based on the task. Load only the file you need — do not preload all of them.

These apply to every provider and every command.

Output

• stdout: data-only JSON by default (just the array or object, no wrapper)
• stderr: errors as JSON, warnings as plain text
• --envelope: wraps stdout with { "data": ..., "meta": ..., "paging": ... }
• Formats: --format json|jsonl|csv, --output <path>, --pretty

Config precedence

• Secrets: shell env > OS credential store. Never from flags or config files.
• Non-secrets: CLI flags > shell env > agent-ads.config.json
• Guided local auth setup: agent-ads auth
• Persistent provider auth: agent-ads <provider> auth set
• Shell override / CI: provider-specific env vars (e.g. META_ADS_ACCESS_TOKEN, GOOGLE_ADS_REFRESH_TOKEN, TIKTOK_ADS_ACCESS_TOKEN, PINTEREST_ADS_REFRESH_TOKEN, LINKEDIN_ADS_ACCESS_TOKEN, X_ADS_CONSUMER_KEY)
• Linux secure storage requires a running Secret Service provider (GNOME Keyring, KWallet)

Exit codes

Global flags

Pagination flags differ by provider — see each provider's routing guide for details.

• Do not drop the provider prefix (agent-ads meta ..., not agent-ads ...).
• Do not invent cross-provider abstractions (no shared campaign/report/measurement schema).
• Do not reuse Meta auth env vars (META_ADS_ACCESS_TOKEN) for other providers.
• Do not guess flag names — use agent-ads <provider> <command> --help to confirm.