google-ads-cli

CLI for the Google Ads gRPC API. Provides campaign management, conversion tracking, keyword management, search term reports, and geographic performance reports.

Installation

Download the latest release binary for your platform from the Releases page.

# Linux amd64
curl -sSfL https://github.com/Parcha-ai/google-ads-cli/releases/latest/download/google-ads-linux-amd64 \
  -o /usr/local/bin/google-ads && chmod +x /usr/local/bin/google-ads

# macOS arm64 (Apple Silicon)
curl -sSfL https://github.com/Parcha-ai/google-ads-cli/releases/latest/download/google-ads-darwin-arm64 \
  -o /usr/local/bin/google-ads && chmod +x /usr/local/bin/google-ads

Or build from source:

go build -o google-ads .

Configuration

Set the following environment variables:

Variable	Required	Description
GOOGLE_ADS_DEVELOPER_TOKEN	Yes	Google Ads API developer token
GOOGLE_ADS_CLIENT_ID	Yes	OAuth2 client ID
GOOGLE_ADS_CLIENT_SECRET	Yes	OAuth2 client secret
GOOGLE_ADS_REFRESH_TOKEN	Yes	OAuth2 refresh token
GOOGLE_ADS_CUSTOMER_ID	Yes	Google Ads customer ID
GOOGLE_ADS_LOGIN_CUSTOMER_ID	No	MCC account ID (for manager accounts)

Usage

All commands support --json for JSON output.

Account Info

google-ads account info
google-ads account info --json

Campaigns

# List all campaigns with metrics
google-ads campaigns list
google-ads campaigns list --date-range LAST_30_DAYS

# Detailed report for a specific campaign
google-ads campaigns report 12345678 --date-range LAST_7_DAYS

Conversions

# List conversion actions
google-ads conversions list-actions

# Push enhanced conversions from JSONL file
google-ads conversions push-conversions --action "Purchase" --file conversions.jsonl

# Push from stdin
cat conversions.jsonl | google-ads conversions push-conversions --action "Purchase" --file -

# Push inline JSON
google-ads conversions push-conversions --action "Purchase" \
  --inline '[{"email":"user@example.com","value":99.99,"currency":"USD","time":"2026-03-19 12:00:00-05:00"}]'

# Dry run
google-ads conversions push-conversions --action "Purchase" --file conversions.jsonl --dry-run

Keywords

# List keywords in an ad group
google-ads keywords list 12345678

# Add negative keyword to a campaign
google-ads keywords add-negative 12345678 "free trial" --match-type EXACT

Search Terms

# Search terms report
google-ads search-terms
google-ads search-terms --campaign 12345678 --date-range LAST_30_DAYS --limit 100

Geographic Report

google-ads geo-report
google-ads geo-report --date-range LAST_30_DAYS

License

Apache 2.0