Google Ads CLI

gads 是我为 Google Ads API 做的一层安全、清晰、可组合的命令行界面。它把 Google 官方 Python 客户端包装成适合开发者、投放团队和 AI Agent 使用的命令：既能查数据，也能谨慎地执行真实操作。

这个项目已经以 Apache-2.0 License 完整开源，可直接安装和使用。

五分钟开始使用

需要 Python 3.11+ 和 uv：

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

如果还希望安装仓库内附带的 Codex Skill：

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

首次连接 Google Ads 时，需要一个经理账号的 developer token，以及 Google Cloud 中创建的 OAuth 2.0 Desktop app 凭据。项目 README 提供了从申请凭据到首次查询的完整教程。

为什么它更安全

每一个写操作都有三个明确阶段：

1. Plan：默认模式，只在本地构造并展示请求，不会修改账号

2. Validate：使用 --validate-only 交给 Google Ads API 校验，但不实际应用

3. Execute：只有显式传入 --execute 才会真正执行，并写入脱敏审计日志

新建的 App Campaign 还会强制保持 PAUSED，把“创建”和“开始花费”拆成两个可复核的动作。

能做什么

• 发现可访问账号并递归查看经理账号层级

• 运行任意 GAQL，查询字段并输出表格、JSON、JSONL 或 CSV

• 查看广告系列、预算、广告组、广告、素材和转化动作

• 暂停、启用或删除广告系列，更新每日预算

• 原子化创建 App Campaign，上传图片和 YouTube 素材

• 应用版本化的通用 GoogleAdsService.Mutate YAML

• 为 Codex 等 AI Agent 提供同一套带保护栏的操作流程

为自动化和 Agent 设计

CLI 的每个命令都能稳定地输出结构化数据；危险操作则需要显式升级权限。仓库内的 Codex Skill 复用了相同的 plan、validate、execute 工作流，减少 AI Agent 临时拼接 API 请求时的风险。

项目源代码、安装说明和完整命令参考都在 GitHub。

---

这是一个独立开源项目，与 Google 不存在隶属、赞助或背书关系。Google Ads 是 Google LLC 的商标。