Google Ads CLI Skill

You have access to google-ads-open-cli, a read-only CLI for the Google Ads API (v23). Use it to query ad accounts, pull performance stats, and run custom GAQL queries.

Quick start

# Check if the CLI is available
google-ads-open-cli --help

# List accessible accounts
google-ads-open-cli customers

If the CLI is not installed, install it:

npm install -g google-ads-open-cli

Authentication

The CLI requires two credentials: an OAuth2 access token and a developer token. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variables: GOOGLE_ADS_ACCESS_TOKEN + GOOGLE_ADS_DEVELOPER_TOKEN
3. Auto-detected file: ~/.config/google-ads-open-cli/credentials.json

For MCC (manager) accounts, also set GOOGLE_ADS_LOGIN_CUSTOMER_ID.

Before running any command, verify credentials are configured by running google-ads-open-cli customers. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Manager Account (MCC)
 └── Customer Account (10-digit ID, e.g. 1234567890)
      ├── Campaign
      │    └── Ad Group
      │         ├── Ad (Ad Group Ad)
      │         └── Keyword (Ad Group Criterion)
      ├── Campaign Budget
      ├── Conversion Action
      ├── User List (remarketing)
      └── Asset (images, videos, sitelinks)

Customer IDs are 10-digit numbers. Dashes are stripped automatically.

Monetary values

Google Ads uses micros: 1 currency unit = 1,000,000 micros. All cost/bid/budget values returned by the CLI are in micros. Always divide by 1,000,000 when presenting monetary values to the user.

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).

Built-in commands

Account discovery

# List all accessible accounts
google-ads-open-cli customers

# Get details for a specific account
google-ads-open-cli customer 1234567890

# List sub-accounts under an MCC
google-ads-open-cli account-hierarchy 1234567890

Browsing entities

# Campaigns (filter by status: ENABLED, PAUSED, REMOVED)
google-ads-open-cli campaigns 1234567890
google-ads-open-cli campaigns 1234567890 --status ENABLED

# Get a specific campaign
google-ads-open-cli campaign 1234567890 98765

# Campaign budgets
google-ads-open-cli campaign-budgets 1234567890

# Ad groups (filter by campaign, status)
google-ads-open-cli ad-groups 1234567890 --campaign 98765

# Get a specific ad group
google-ads-open-cli ad-group 1234567890 11111

# Ads (filter by campaign, ad group, status)
google-ads-open-cli ads 1234567890 --campaign 98765 --ad-group 11111

# Get a specific ad (requires ad-group-id and ad-id)
google-ads-open-cli ad 1234567890 11111 22222

# Keywords
google-ads-open-cli keywords 1234567890 --campaign 98765 --status ENABLED

All listing commands support --limit <n> (default 100).

Performance stats