lucianfialho/gmp-cli/gmp-ads

ads (Google Ads REST API)

PREREQUISITE: Read ../gmp-shared/SKILL.md for auth, global flags, and output formats.

EXTRA AUTH: Google Ads requires a developer token. Set it with:

```bash

gmp auth set-developer-token YOUR_TOKEN

```

If using a Manager Account (MCC), also set:

```bash

gmp auth set-login-customer-id 1234567890

```

gmp ads <command> [flags]

Commands

Quick Reference

List accounts

# Simple list (no MCC needed)
gmp ads accounts
 
# Detailed list via MCC
gmp ads accounts -c 1234567890 -f table

Ad group performance

gmp ads adgroups -c 1234567890 -f table
gmp ads adgroups -c 1234567890 --campaign "Brand" -f table

Keyword performance

gmp ads keywords -c 1234567890 -f table
gmp ads keywords -c 1234567890 --campaign "Brand" -l 20 -f table

Search terms

gmp ads search-terms -c 1234567890 -f table
gmp ads search-terms -c 1234567890 --campaign "Brand" -f table

Raw GAQL query

gmp ads query -c 1234567890 -q "SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS"

Sorting (--sort, --order)

campaigns, adgroups, keywords, and search-terms each take --sort <field> --order <asc|desc> (default desc), rewriting the report's ORDER BY clause. Each command only accepts the field names it actually outputs:

gmp ads campaigns -c 1234567890 --sort cost --order desc -f table       # biggest spenders first
gmp ads keywords -c 1234567890 --sort qualityScore --order asc -f table # worst quality score first

An unknown --sort value errors with the exact list of fields that command accepts.

Date Range Values

Google Ads uses predefined date range constants:

Tips

• Customer IDs can include dashes (123-456-7890) or not (1234567890) -- both work.
• Costs are returned in micros and automatically converted (divided by 1,000,000).
• CTR and rates are automatically formatted as percentages.
• Use gmp ads query for any GAQL query not covered by built-in commands.
• GAQL reference: the query language supports SELECT, FROM, WHERE, ORDER BY, LIMIT.