Google Ads CLI (gads)

A command-line tool for managing Google Ads campaigns, ad groups, and ads across multiple accounts.

Setup

Prerequisites

• Node.js 22+
• A Google Ads account (get one at ads.google.com)

1. Google Cloud Project & OAuth Credentials

1. Go to Google Cloud Console and create a new project (or use an existing one).
2. Enable the Google Ads API: Navigate to APIs & Services → Library, search for "Google Ads API", and click Enable.
3. Set up the OAuth consent screen: Go to Google Auth Platform → Overview → Get Started.
   • App name: whatever you want (e.g. "Google Ads CLI")
   • User support email: your email
   • Audience: External
   • Contact email: your email
   • Agree to the User Data Policy
   • Click Create
4. Publish the app (optional but recommended): Go to Google Auth Platform → Audience and click Publish app. This avoids having to manually add test users. The app will show an "unverified" warning during OAuth, but you can click through it since it's just for your personal use.
5. Create OAuth credentials: Go to Google Auth Platform → Clients → Create Client.
   • Application type: Desktop app
   • Name: whatever you want
   • Click Create
   • Immediately copy the Client Secret from the dialog — Google no longer lets you view it after closing the dialog. If you miss it, click "Add client secret" on the client detail page to generate a new one.

You now have a Client ID and Client Secret.

2. Google Ads Developer Token

1. Sign in to Google Ads with the account that has a Manager (MCC) account. If you don't have one, create one at ads.google.com/home/tools/manager-accounts/.
2. Navigate to Admin → API Center.
3. Copy your Developer Token. It starts at "Explorer Access" level which is fine for personal use (15,000 operations/day).

3. Configure .env

Copy .env.example to .env and fill in the values:

cp .env.example .env

GOOGLE_ADS_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_ADS_CLIENT_SECRET=GOCSPX-your-client-secret
GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token
GOOGLE_ADS_REFRESH_TOKEN=          # filled in by step 4
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890   # your MCC account ID (no dashes)
GOOGLE_ADS_CUSTOMER_ID=0987654321         # default client account ID (no dashes)

4. OAuth Authentication

Run the auth flow to get a refresh token:

npm run auth

This will:

1. Start a local server on http://localhost:3456
2. Open your browser to Google's OAuth consent page
3. After you grant access, capture the authorization code
4. Exchange it for a refresh token
5. Automatically save it to your .env file

You only need to do this once. The refresh token is long-lived.

5. Link Accounts (if using an MCC)

If your ad accounts aren't already linked to your Manager account:

1. In Google Ads, switch to your Manager account
2. Go to Accounts → Add account → Link existing account
3. Enter the client account ID
4. Click Send Request
5. Switch to the client account, go to Admin → Access and security → Managers
6. Accept the link request

Usage

All commands default to the account set in GOOGLE_ADS_CUSTOMER_ID. Use --customer <id> to target a different account.

Accounts

# List all accessible accounts
gads accounts

Campaigns

# List all campaigns
gads campaigns list

# Create a new search campaign ($10/day budget, starts paused)
gads campaigns create --name "My Campaign" --budget 10

# Update a campaign
gads campaigns update --id 123456 --name "New Name" --status enabled --budget 15

# Pause a campaign
gads campaigns pause --id 123456

# Remove a campaign
gads campaigns remove --id 123456

Ad Groups

# List all ad groups
gads adgroups list

# List ad groups in a specific campaign
gads adgroups list --campaign 123456

# Create an ad group ($2.50 max CPC bid, starts paused)
gads adgroups create --campaign 123456 --name "My Ad Group" --cpc-bid 2.50

# Update an ad group
gads adgroups update --id 789 --name "New Name" --status enabled --cpc-bid 3.00

# Pause / remove an ad group
gads adgroups pause --id 789
gads adgroups remove --id 789

Ads

# List all ads
gads ads list

# List ads in a specific campaign or ad group
gads ads list --campaign 123456
gads ads list --ad-group 789

# Create a Responsive Search Ad (min 3 headlines, min 2 descriptions)
gads ads create \
  --ad-group 789 \
  --url "https://example.com" \
  --headlines "Headline One,Headline Two,Headline Three" \
  --descriptions "First description here,Second description here" \
  --path1 "products" \
  --path2 "best"

# Update an ad's status
gads ads update --ad-group 789 --ad 456 --status enabled

# Pause / remove an ad
gads ads pause --ad-group 789 --ad 456
gads ads remove --ad-group 789 --ad 456

Google Ads Hierarchy

Manager Account (MCC)          ← optional umbrella, holds the developer token
  └── Client Account           ← the billing/advertising unit (one per biz, or one for all)
        └── Campaign           ← budget + targeting settings (can point to any domain)
              └── Ad Group     ← groups related ads + keywords, sets CPC bid
                    ├── Ad     ← the creative (headlines, descriptions, URL)
                    └── Keywords ← what search terms trigger the ad

One client account can run campaigns for multiple domains — just set different final URLs on the ads.

Development

# Run any command during development (without building)
npx tsx src/cli.ts campaigns list

# Type-check
npx tsc --noEmit

# Build to dist/
npm run build