Screenshots

Key Features

Safe Plan / Validate / Execute write workflow

Account discovery and recursive manager hierarchies

Arbitrary GAQL, field discovery, and multi-format output

Campaign, budget, ad group, ad, and conversion operations

Atomic App Campaign creation with image and YouTube assets

Bundled Codex Skill and sanitized JSONL audit trail

More About This Project

Google Ads CLI

Name: Google Ads CLI
Author: Daji

gads is a safe, clear, and composable command-line layer for the Google Ads API. It turns Google's official Python client into practical commands for developers, growth teams, and AI agents—covering both reporting and carefully guarded account operations.

The complete project is open source under the Apache-2.0 License and ready to install.

Start in Five Minutes

With Python 3.11+ and uv installed:

uv tool install git+https://github.com/icoolqin/google-ads-cli.git
gads --version

To install both the CLI and its bundled Codex Skill:

git clone https://github.com/icoolqin/google-ads-cli.git
cd google-ads-cli
./scripts/install-local.sh

Connecting to Google Ads requires a manager-account developer token and OAuth 2.0 Desktop app credentials from Google Cloud. The project README walks through the complete setup and first query.

A Safer Write Workflow

Every mutation has three explicit stages:

Plan: the default; builds and displays the request locally without changing an account
Validate: --validate-only asks the Google Ads API to verify the request without applying it
Execute: only --execute applies the change and records a sanitized audit entry

New App Campaigns are always created in PAUSED status, keeping creation separate from the decision to start spending.

What It Can Do

Discover accessible accounts and recursively explore manager hierarchies
Run arbitrary GAQL, discover fields, and output tables, JSON, JSONL, or CSV
Inspect campaigns, budgets, ad groups, ads, assets, and conversion actions
Pause, enable, or remove campaigns and update daily budgets
Create atomic App Campaigns with image and YouTube assets
Apply versioned generic GoogleAdsService.Mutate YAML manifests
Give Codex and other AI agents the same guarded operating workflow

Built for Automation and Agents

Commands produce stable structured output, while risky operations require explicit escalation. The bundled Codex Skill follows the same plan, validate, and execute model, reducing the risk of an AI agent improvising direct API mutations.

Source code, setup instructions, and the full command reference are available on GitHub.

This is an independent open-source project. It is not affiliated with or endorsed by Google. Google Ads is a trademark of Google LLC.