Google Ads CLI

README

# Google Ads CLI

[English](https://github.com/icoolqin/google-ads-cli/blob/main/README.md) · [简体中文](https://github.com/icoolqin/google-ads-cli/blob/main/README.zh-CN.md)

![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB)
![Google Ads API v25](https://img.shields.io/badge/Google%20Ads%20API-v25-4285F4)
![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)

`gads` 是一个安全、可脚本化、适合 AI Agent 使用的 Google Ads API 命令行工具。它基于
Google 官方 Python 客户端，提供账号发现、GAQL 报表、Campaign 操作、App Campaign
创建、素材上传和通用 mutation 等实用能力。

仓库还包含一个 Codex skill，让 AI Agent 也遵循同一套安全流程，而不是临时拼接未经验证的
API 请求。

> [!IMPORTANT]
> 这是一个独立的开源项目，与 Google 没有关联，也未获得 Google 背书。Google Ads 是
> Google LLC 的商标。

## 为什么写操作分成三步

每个修改账号的命令都有三种明确模式：

| 模式 | 参数 | 实际行为 |
| --- | --- | --- |
| 计划 | 无 | 在本地构造并校验 protobuf 请求，然后打印操作计划；不需要凭证，也不会发起网络请求。 |
| 验证 | `--validate-only` | 把请求交给 Google Ads 校验，但不应用修改。 |
| 执行 | `--execute` | 真正应用修改，并在本地审计日志中记录经过脱敏的摘要。 |

默认是计划模式。复制粘贴一条命令不会仅仅因为语法正确就开始花钱。新建 App Campaign
永远从 `PAUSED` 状态开始，启用广告是一个独立、可复核的动作。

## 能做什么

- 完成单用户 OAuth 授权并创建私密的 `google-ads.yaml`
- 管理多个不含密钥的账号 profile
- 发现直接可访问账号和递归的经理账号层级
- 执行、校验任意 GAQL，并查询可用的 Google Ads 字段
- 输出表格、JSON、JSONL 或 CSV
- 执行账号、Campaign、Ad Group、广告、每日表现、转化、单素材评级和广告网络分布等常用报表
- 查看 Campaign、预算、Ad Group、广告、素材和转化操作
- 暂停、启用或移除 Campaign，修改每日预算
- 原子化创建包含预算、定向、Ad Group、App Ad 和素材的 App Campaign
- 上传图片素材、创建 YouTube 素材
- 查看 App Ad 真实挂载的素材，并原位增删，无需重建 Ad Group
- 查看账户余额、扣税后的可投净额和可投天数
- 查看账户变更历史（谁在什么时候改了什么）
- 查询地理位置和语言常量
- 执行带 API 版本的 `GoogleAdsService.Mutate` YAML 清单
- 用确定性的计划哈希保存不含密钥的 JSONL 审计记录

## 开始前需要准备

你需要：

1. Python 3.11 或更高版本。
2. [`uv`](https://docs.astral.sh/uv/getting-started/installation/)。
3. 拥有 developer token 的 Google Ads 经理账号。
4. 已启用 Google Ads API 的 Google Cloud 项目。
5. 一个 OAuth 2.0 **桌面应用**客户端 JSON。
6. 能访问目标 Ads 账号的 Google 用户。

Google 会给每个 developer token 分配访问级别：

| 访问级别 | 可访问账号 | 每日操作数 |
| --- | --- | ---: |
| Test | 测试账号 | 15,000 |
| Explorer | 测试和正式账号 | 正式账号 2,880；测试账号 15,000 |
| Basic | 测试和正式账号 | 15,000 |
| Standard | 测试和正式账号 | 大部分服务不限量 |

正式使用前，请以 Google 最新的
[developer token 指南](https://developers.google.com/google-ads/api/docs/api-policy/developer-token)
和[访问级别表](https://developers.google.com/google-ads/api/docs/api-policy/access-levels)为准。

## 五分钟安装

### 1. 安装 `uv`

macOS 使用 Homebrew：

```bash
brew install uv
```

Linux、Windows 或其他安装方式请查看
[uv 官方说明](https://docs.astral.sh/uv/getting-started/installation/)。

### 2. 下载仓库

克隆或下载仓库，然后进入仓库根目录：

```bash
cd google-ads-cli
```

### 3. 安装 CLI 和 Codex skill

```bash
./scripts/install-local.sh
gads --version
```

安装脚本会创建隔离的、可编辑的 `uv` tool，并把 `skills/google-ads` 链接到 Codex
skills 目录。只安装 CLI：

```bash
uv tool install .
```

只在仓库里开发、不安装全局命令：

```bash
uv sync --dev
uv run gads --help
```

## 配置 Google 访问权限

### 1. 获取 developer token

登录 Google Ads **经理账号**，打开
[API Center](https://ads.google.com/aw/apicenter)，申请 developer token。这里的“经理账号”
是账号类型（MCC），不是客户账号中的管理员角色。如果页面提示 API Center 只对经理账号
开放，请在 Google Ads 账号选择器中切换到 MCC，或先创建一个经理账号。

新申请可能会被自动批准为 Explorer 访问权限；否则会先获得测试账号访问权限。Explorer、
Basic 和 Standard 可以在各自限额内访问正式账号。具体以 Google 当前的
[developer token 访问权限说明](https://developers.google.com/google-ads/api/docs/api-policy/developer-token)
为准。

### 2. 创建 OAuth 桌面应用

在 Google Cloud 中：

1. 创建或选择一个项目。
2. 启用 **Google Ads API**。
3. 配置 OAuth consent screen。
4. 创建应用类型为 **Desktop app** 的 OAuth 客户端。
5. 下载客户端 JSON，并把它放在本仓库之外。

OAuth 应用的发布状态为 **Testing** 时，需要在 **Google Auth Platform → Audience →
Test users** 中加入每个将要授权 CLI 的 Google 用户。MCC 管理员不会自动成为 OAuth
测试用户。Ads scope 的测试授权（包括离线 refresh token）会在 7 天后过期；需要长期稳定
运行时，应把应用发布为 Production，并在 Google 要求时完成验证。

控制台步骤如有变化，请参考 Google 的
[OAuth 指南](https://developers.google.com/google-ads/api/docs/oauth/overview)。

### 3. 授权

运行：

```bash
gads auth login \
  --client-secrets /absolute/path/to/client_secret.json \
  --login-customer-id 1111111111 \
  --customer-id 2222222222
```

developer token 会通过隐藏输入框读取。命令会打开 Google OAuth 页面，创建权限为
`0600` 的凭证 YAML，并创建一个不含密钥的 CLI profile。登录页会强制显示账号选择器；
请选择能够直接访问 `--login-customer-id` 所指定 MCC 的 Google 用户。

- `customer_id` 是实际要管理 Campaign 和数据的客户账号。
- `login_customer_id` 是用来访问该客户账号的经理账号；直接访问客户账号时可以省略。
- 可以输入带连字符的 ID，CLI 会规范化为 10 位数字。

请区分下面四种身份：

| 项目 | 作用 |
| --- | --- |
| developer token 所有者 | 在 API Center 签发 token 的 MCC。 |
| OAuth 客户端 | Google Cloud 项目中的 Desktop app。 |
| OAuth Google 用户 | 实际同意授权的人，必须拥有相应 Google Ads 权限。 |
| login/target customer | 请求头中的 MCC，以及真正查询数据的客户账号。 |

无法自动打开浏览器时，加上 `--no-browser`。在能够访问同一本地回调地址的浏览器中打开
命令打印的 URL 并完成授权。

### 4. 验证连接

```bash
gads auth test
gads accounts accessible
gads accounts hierarchy --manager-id 1111111111
gads accounts show
```

`accounts accessible` 只列出直接访问的账号；经理账号下面的客户账号请用
`accounts hierarchy` 查看，并显式传入经理账号 ID，不要让它从客户账号 profile 开始。

## 第一次读取数据

全局参数必须放在命令组**之前**：

```bash
gads --profile default --customer-id 2222222222 --format json campaigns list
```

常用读取命令：

```bash
gads --format json accounts show
gads --format json budgets list
gads --format json adgroups list
gads --format json ads list
gads --format json assets list
gads --format json conversions list
```

预置报表：

```bash
gads reports list
gads --format json reports run campaigns --date-range LAST_30_DAYS
gads --format csv reports run daily --date-range 2026-07-01:2026-07-28
```

原始 GAQL：

```bash
gads query validate --file examples/app-campaign-performance.gaql
gads --format jsonl query run \
  --file examples/app-campaign-performance.gaql \
  --limit 1000
```

不确定字段名时直接查询：

```bash
gads --format json fields describe campaign.app_campaign_setting.app_id
gads --format json fields search 'metrics.%' --limit 50
```

## 第一次安全写入

同一条命令依次经过计划、验证、执行和回读：

```bash
# 1. 本地计划；账号不会变化
gads campaigns set-status 123456789 PAUSED

# 2. 交给 Google 校验；账号仍不会变化
gads campaigns set-status 123456789 PAUSED --validate-only

# 3. 真正应用
gads campaigns set-status 123456789 PAUSED --execute

# 4. 回读验证
gads campaigns get 123456789
```

`--execute` 和 `--validate-only` 不能同时使用。日常停投优先选择 `PAUSED`；移除是另一种
通常不可逆的 Google Ads 生命周期操作。

按账号币种修改预算：

```bash
gads budgets set-amount 987654321 50