name: google-ads-cli-skill description: Comprehensive operational guide for agents using Google Ads CLI. version: 1.0.0 tools:

• google-ads-cli

Google Ads CLI Skill (google-ads-cli)

This skill trains an agent to operate google-ads-cli reliably in automation and agentic pipelines.

1) Tool identity

• Package: google-ads-cli
• Binary: google-ads-cli
• Local dev entry: npm run dev -- <command>

2) Capabilities

The CLI supports:

• Setup and credential/profile management
• OAuth authentication
• Account listing
• Campaign and ad group inspection
• Keyword Planner idea generation
• Geo target location lookup
• GAQL query execution

3) Prerequisites and readiness checks

Preflight checks:

1. Node >= 18
2. Setup completed (setup)
3. Authenticated profile (auth)
4. Required account context exists (customer ID/login customer ID)

Readiness commands:

google-ads-cli --version
google-ads-cli --help
google-ads-cli config
google-ads-cli profiles --list

4) First-time workflow

4.1 Setup

google-ads-cli setup

Provide:

• OAuth client ID
• OAuth client secret
• Developer token
• Customer ID (no dashes)
• Optional login customer ID for MCC use

4.2 Authenticate

google-ads-cli auth

Use profile-specific auth if needed:

google-ads-cli auth --profile my-profile

4.3 Verify access

google-ads-cli accounts
google-ads-cli campaigns --limit 5

5) Command reference for agents

Auth/config:

• setup
• auth
• logout
• profiles --list
• profiles --switch
• config

Accounts:

• accounts [--json]

Campaigns/ad groups:

• campaigns [-l <limit>] [--json]
• campaign <id> [--json]
• ad-groups -c <campaign-id> [-l <limit>] [--json]

Keyword planning:

• keyword-ideas [keywords...] [--url <url>] [--language <code>] [--location <codes...>] [--limit <n>] [--json]
• locations <search> [-l <limit>] [--json]

Reporting:

• query <gaql> [-f <file>] [--json]

Profile scoping is available via -p, --profile on most commands.

6) High-confidence automation runbooks

6.1 Campaign snapshot

google-ads-cli campaigns --limit 25 --json

6.2 Drill into a campaign then ad groups

google-ads-cli campaign 1234567890 --json
google-ads-cli ad-groups --campaign-id 1234567890 --limit 50 --json

6.3 Keyword ideation pipeline

google-ads-cli keyword-ideas "seo tools" "content marketing" --location 2840 --limit 100 --json

6.4 GAQL reporting

google-ads-cli query "SELECT campaign.id, campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_30_DAYS LIMIT 50" --json

or from file:

google-ads-cli query "" --file ./report.gaql --json

7) Agent operating standards

1. Prefer --json for machine parsing and deterministic outputs.
2. Validate authentication before expensive queries.
3. Keep profile/account context explicit for multi-account environments.
4. Validate required options (--campaign-id, GAQL string/file).
5. Avoid mutative assumptions: this CLI is mostly read/reporting oriented.

8) Structured output guidance

For agent pipelines, capture:

• command
• profile used
• customer context
• result count
• key IDs returned
• errors with remediation

When parsing tables, prefer re-running with --json rather than scraping table output.

9) Failure handling patterns

Not authenticated

google-ads-cli auth

Missing credentials/profile

google-ads-cli setup
google-ads-cli profiles --list

Developer token limitations

If token in test mode, restrict operations to owned/managed accounts and report limitation.

Customer/account mismatch

Re-run setup or use the intended profile:

google-ads-cli config --profile my-profile

OAuth callback issues (port conflict)

Check local process conflicts and retry auth flow.

10) Multi-profile best practices

• One profile per client/account boundary.
• Use explicit --profile in automation jobs.
• Validate active profile before execution (config, profiles --list).

11) Minimal agent command packs

Read-only health check:

google-ads-cli config
google-ads-cli accounts --json
google-ads-cli campaigns --limit 5 --json

Keyword research pack:

google-ads-cli locations "United States" --json
google-ads-cli keyword-ideas "b2b saas crm" --location 2840 --limit 75 --json

GAQL reporting pack:

google-ads-cli query "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS LIMIT 25" --json

12) Security basics

• Never print client secret, refresh tokens, or raw credential files.
• Never commit local config/secrets.
• Keep OAuth data local to operator machine.
• Use least-privilege access and intended customer IDs only.