Package Exports

@optima-chat/google-ads-cli
@optima-chat/google-ads-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@optima-chat/google-ads-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Google Ads CLI

为客户创建和管理 Google Ads 广告的专业工具 - 专为服务提供商和 Claude Code 设计

定位

本工具专为服务提供商设计，用于为客户创建和管理 Google Ads 广告账号。

🏢 服务提供商视角 - 使用您自己的 OAuth2 凭据（一次性配置）
👥 多客户管理 - 为多个客户创建和管理独立的广告账号
🎯 客户资产 - 广告系列、关键词、广告内容都属于客户
🤖 AI 友好 - 可被 Claude Code 自然语言调用，简化客户服务流程

特性

🎯 完整的客户账号管理 - 创建账号、配置账单、管理权限
📢 广告投放管理 - 创建广告系列、广告组、关键词、文案
📊 效果分析 - 查看客户广告表现数据
⚡ 直接调用 - 使用 Google Ads API 官方 SDK，性能优秀
📋 多格式输出 - 表格、JSON、CSV 多格式支持
🔐 OAuth2 认证 - 完整的 OAuth2 授权流程，自动 token 刷新
💎 架构简洁 - 2 层架构，无额外依赖，部署简单

快速开始（服务提供商）

第一步：一次性设置（服务提供商配置）

# 安装
npm install -g @optima-chat/google-ads-cli@latest

# 1. 复制环境变量模板
cp .env.example .env

# 2. 编辑 .env 文件，填入以下信息：
#    - GOOGLE_ADS_DEVELOPER_TOKEN（从 https://ads.google.com/aw/apicenter 获取）
#    - GOOGLE_ADS_CLIENT_ID（从 https://console.cloud.google.com 获取）
#    - GOOGLE_ADS_CLIENT_SECRET（从 https://console.cloud.google.com 获取）
#    - GOOGLE_ADS_CUSTOMER_ID（你的 MCC 管理账号 ID）

# 3. OAuth2 登录授权（会自动打开浏览器，授权后 refresh token 自动保存到 .env）
google-ads auth login

# 4. 验证配置
google-ads account list

第二步：为客户管理广告

# 为客户创建 Google Ads 账号
google-ads account create \
  --merchant-id <客户商户ID> \
  --currency USD \
  --timezone "America/New_York" \
  --name "客户公司名称"

# 检查客户账号状态（账单、权限等）
google-ads account check -c <CUSTOMER_ID>

# 为客户创建广告系列
google-ads campaign create \
  -c <CUSTOMER_ID> \
  -n "客户的广告系列名称" \
  -b 50

# 查看客户的广告系列
google-ads campaign list -c <CUSTOMER_ID>

# 为客户添加关键词
google-ads keyword add <AD_GROUP_ID> \
  --keywords "产品关键词1,产品关键词2" \
  --match-type EXACT

# 查看客户的关键词
google-ads keyword list -c <CUSTOMER_ID> --limit 20

# 执行 GAQL 查询分析客户广告表现
google-ads query -c <CUSTOMER_ID> \
  -q "SELECT campaign.id, campaign.name, metrics.impressions FROM campaign" \
  --pretty

架构

服务提供商 (一次性 OAuth2 配置)
        ↓
   Claude Code / AI
        ↓
  google-ads-cli (TypeScript)
        ↓ (Google Ads API SDK)
   Google Ads API
        ↓
  多个客户的广告账号

设计理念:

服务提供商使用自己的凭据（MCC 管理账号）
为多个客户创建和管理独立的广告账号
架构简洁优美，为长远计

配置说明

本工具采用纯环境变量配置，符合 12-factor app 最佳实践。

环境变量

在项目根目录创建 .env 文件（或设置系统环境变量）：

# MCC 管理账号 ID
GOOGLE_ADS_CUSTOMER_ID=your-mcc-account-id

# Developer Token（从 https://ads.google.com/aw/apicenter 获取）
GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token

# OAuth2 客户端凭据（从 https://console.cloud.google.com 获取）
GOOGLE_ADS_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_ADS_CLIENT_SECRET=your-client-secret

# OAuth2 Refresh Token（通过 google-ads auth login 自动获取）
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token

获取凭据

创建 MCC 账号：访问 https://ads.google.com
获取 Developer Token：访问 https://ads.google.com/aw/apicenter
配置 OAuth2：
- 访问 https://console.cloud.google.com
- 创建项目并启用 Google Ads API
- 创建 OAuth 2.0 客户端 ID（桌面应用类型）
- 获取 Client ID 和 Client Secret

命令概览

基础命令

google-ads --version - 查看版本
google-ads --help - 查看帮助

认证管理 (`google-ads auth`)

login - OAuth2 登录
logout - 退出登录
status - 查看认证状态

账号管理 (`google-ads account`)

list [--json] - 列出可访问的账号
info <customer-id> [--json] - 查看账号详情
check -c <customer-id> [--json] - 检查账号配置状态（账单、权限等）
create --merchant-id <id> --currency <code> --timezone <tz> --name <name> - 为客户创建账号

广告系列 (`google-ads campaign`)

list -c <customer-id> [--status <status>] [--limit <n>] [--json] - 列出广告系列
info -c <customer-id> <campaign-id> [--json] - 查看广告系列详情
create -c <customer-id> -n <name> -b <budget> [--status <status>] - 创建广告系列
delete -c <customer-id> <campaign-id> - 删除广告系列

广告组 (`google-ads ad-group`)

list -c <customer-id> --campaign-id <id> [--json] - 列出广告组
create -c <customer-id> --campaign-id <id> -n <name> -b <bid> - 创建广告组
delete -c <customer-id> <ad-group-id> - 删除广告组

关键词 (`google-ads keyword`)

list -c <customer-id> [--campaign-id <id>] [--status <status>] [--limit <n>] [--json] - 列出关键词
add <ad-group-id> --keywords <words> [--match-type <type>] - 添加关键词
delete -c <customer-id> <keyword-id> - 删除关键词

GAQL 查询 (`google-ads query`)

query -c <customer-id> -q "<gaql>" [--json] [--pretty] - 执行 GAQL 查询
query -c <customer-id> -f <file> [--json] [--pretty] - 从文件执行查询

查看完整命令文档了解更多。

双模式设计

结构化命令（80% 场景）

简单、明确、LLM 易理解

# 为客户管理广告
google-ads campaign list -c <CUSTOMER_ID>
google-ads campaign create -c <CUSTOMER_ID> -n "广告系列名称" -b 100
google-ads keyword add <ad-group-id> --keywords "产品关键词1,产品关键词2"

GAQL 查询（20% 场景）

灵活、强大、适合复杂分析

google-ads query "
  SELECT
    campaign.name,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
  ORDER BY metrics.clicks DESC
"

开发状态

🎉 核心功能已实现

技术方案设计
架构决策（直接 API 调用）
OAuth2 认证实现（login/logout/status）
纯环境变量配置（符合 12-factor app）
账号管理命令（account list/info/check/create）
广告系列命令（campaign list/info/create/delete）
广告组命令（ad-group list/create/delete）
关键词管理命令（keyword list/add/delete）
GAQL 查询支持（query）
Google Ads Client 封装
集成测试
发布到 NPM（当前版本 v0.2.0）
GitHub Actions 自动化发布
客户账号创建 API 实现（当前为手动指引）
广告文案管理命令
效果分析和报表命令
单元测试

技术栈

CLI 框架: commander.js
HTTP 客户端: axios
输出格式化: chalk + cli-table3
交互提示: inquirer
配置管理: conf
开发工具: TypeScript + tsx

发布流程

本项目使用 GitHub Actions 自动发布到 NPM：

# 更新版本号（patch/minor/major）
npm version patch

# 推送 tag 触发自动发布
git push --follow-tags

GitHub Actions 会自动：

运行测试和构建
发布到 NPM
创建 GitHub Release
生成 changelog

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License - 详见 LICENSE

联系我们

官网: https://www.optima.shop
社区: https://optima.chat
GitHub: https://github.com/Optima-Chat/google-ads-cli

@optima-chat/google-ads-cli