agent-ads
Skill

Install the skill

Install the public skill if you use Codex or Claude Code with agent-ads. It gives the agent a simple playbook for checking providers, checking auth, and using the real commands.

Install
Add the public skill
bash
npx skills add bengoism/agent-ads
Why use it

Useful with Codex and Claude Code

The skill helps the agent understand how to use agent-ads without guessing. It points the agent to the right provider docs and keeps commands provider-specific.

  • Start by listing providers and checking auth status
  • Use commands like agent-ads meta ... or agent-ads tiktok ...
  • Follow the provider guides instead of inventing shared ads commands
Use Cases

What agents use it for

Use the skill for direct, provider-specific CLI work across the supported ad platforms.

Use the skill for direct, provider-specific CLI work across the supported ad platforms.

  • Check available providers: agent-ads providers list
  • Check auth status across providers: agent-ads auth status
  • Discover Meta businesses and ad accounts
  • List Google Ads customers or run GAQL queries
  • Query TikTok, Pinterest, LinkedIn, or X reporting surfaces
  • Inspect creatives, pixels, audiences, and other provider-native objects
  • Run agent-ads <provider> doctor before troubleshooting auth or config
Guide

Command Syntax Rules

Every command starts with agent-ads <provider>. The CLI stays provider-first because each platform has its own auth model, object graph, and reporting semantics.

Every command starts with agent-ads <provider>. The CLI stays provider-first because each platform has its own auth model, object graph, and reporting semantics.

  • Canonical: agent-ads meta insights query ...
  • Never: agent-ads insights query ...
  • Never: agent-ads meta:insights:query
Guide

Provider Routing

Start with the provider guide that matches the platform you need.

Start with the provider guide that matches the platform you need.

ProviderFirst commandReference guide
metaagent-ads meta --helpreferences/meta.md
googleagent-ads google --helpreferences/google.md
tiktokagent-ads tiktok --helpreferences/tiktok.md
pinterestagent-ads pinterest --helpreferences/pinterest.md
linkedinagent-ads linkedin --helpreferences/linkedin.md
xagent-ads x --helpreferences/x.md

Check live: agent-ads providers list

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

Load only the provider guide you need. Do not preload all reference files.

Guide

Shared Behavior

These rules apply to every provider.

These rules apply to every provider.

Output

  • stdout: data-only JSON by default
  • stderr: errors as JSON, warnings as plain text
  • --envelope: wraps stdout with { "data": ..., "meta": ..., "paging": ... }
  • Common flags: --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
  • Linux secure storage requires a running Secret Service provider such as GNOME Keyring or KWallet

Exit codes

CodeMeaning
0Success
1Transport or internal error
2Config or argument error
3Meta API error
4TikTok API error
5Google API error
6Pinterest API error
7LinkedIn API error
8X API error

Global flags

FlagDefaultWhat it does
--config <path>agent-ads.config.jsonConfig file path
--format json|jsonl|csvjsonOutput format
--output <path>stdoutWrite to file (- for stdout)
--prettyoffPretty-print JSON
--envelopeoffWrap data with metadata, paging, warnings
--include-metaoffAdd metadata columns in CSV mode
--api-version <v>provider defaultProvider API version override
--timeout-seconds <n>60HTTP request timeout
-q / -vwarnQuiet mode or verbose logging (-vv for debug)

Pagination flags differ by provider. Use agent-ads <provider> --help or the provider guide to confirm the exact shape.

Guide

Common Issues

These are the first checks worth making when commands fail.

These are the first checks worth making when commands fail.

ProblemWhat's happeningFix
"My token expired"Meta tokens can be short-lived; TikTok access tokens expire every 24 hours; Pinterest uses OAuth refresh tokensMeta: regenerate at Graph API Explorer then run meta auth set. TikTok: run tiktok auth refresh. Pinterest: run pinterest auth refresh
"I don't know my account ID"Most providers require an explicit account, customer, or advertiser scopeDiscover it first: Meta businesses list / ad-accounts list; Google customers list; TikTok advertisers list; Pinterest ad-accounts list; LinkedIn ad-accounts list; X accounts list
"Permission denied"The token is missing required scopes or account accessRe-check the provider auth guide and reissue credentials with the required read scope
"doctor says credential store unavailable"No OS keychain is available on this machineUse provider-specific shell env vars for that session or CI job
"<provider> says an ID is required"The command is scoped and no default is configuredPass the provider-specific ID flag or set the matching default in providers.<provider> config
"Command not found"The CLI is missing or not on PATHRun agent-ads --version; if needed, install with npm install -g agent-ads
Guide

Stop Conditions

Keep the command model explicit and provider-native.

Keep the command model explicit and provider-native.

  • Do not drop the provider prefix (agent-ads meta ..., not agent-ads ...)
  • Do not invent cross-provider abstractions or shared schemas
  • Do not reuse one provider's auth env vars for another provider
  • Do not guess flag names; confirm with agent-ads <provider> <command> --help