aads — Apple Ads Platform API CLI

aads 是 Apple Ads（苹果广告）Platform API v1 的命令行工具，用它可以查询和管理广告系列（campaigns）、广告组（ad groups）、关键词、广告素材、报表、搜索建议等资源，覆盖官方 OpenAPI 规范中的全部 101 个接口操作。

安装

npm install -g @appstare/aads

安装后直接使用 aads 命令：

aads --help
aads list          # 查看所有可用命令

需要 Node.js 14+。已内置各平台（macOS / Linux / Windows，amd64 / arm64）二进制，无需额外编译。

快速开始

1. 认证

按 Apple 官方 OAuth 流程：本地生成 ES256 密钥对，在 ads.apple.com 的 Account Settings > API 上传公钥，后台返回 teamId / clientId / keyId；privateKey 就是本地保留的 PEM 私钥。然后用一条命令登录：

aads auth login --teamId <teamId> --clientId <clientId> --keyId <keyId> --private-key ~/api_key.pem

• 字段用途（官方文档）：teamId → JWT iss；clientId → JWT sub 和 token 请求的 client_id；keyId → JWT header kid；privateKey 签名 client secret
• 兼容别名：--issuer = --teamId，--client-id = --clientId，--key-id = --keyId
• 私钥支持文件路径、PEM 内容、stdin（-）、base64: 四种传法
• 登录后凭据保存到 ~/.config/aads/config.json，access token 会自动换取并缓存，到期前自动刷新，无需你操心

aads auth status   # 查看认证状态和 token 缓存
aads auth token    # 打印当前 access token（必要时自动刷新）
aads auth logout   # 退出登录

也可以直接用环境变量：

export APPLE_ADS_TEAM_ID=<teamId>
export APPLE_ADS_CLIENT_ID=<clientId>
export APPLE_ADS_KEY_ID=<keyId>
export APPLE_ADS_PRIVATE_KEY=~/api_key.pem
export APPLE_ADS_CONTEXT="orgId=<orgId>"   # X-Ap-Context 头，多账户时用

2. 查看命令

aads list              # 全部命令列表（资源 + 动作 + 说明）
aads list --full       # 带 HTTP 方法和路径
aads list campaigns    # 只看某个资源的命令
aads show campaigns query   # 某个命令的用法、参数、示例
aads schema campaigns create # 请求体字段、类型、枚举

3. 调用接口

命令格式统一为 aads <资源> <动作>，路径参数和查询参数按规范自动生成：

# 查询广告系列（分页）
aads campaigns query --data '{"pagination":{"offset":0,"pageSize":100}}'

# 获取单个广告系列
aads campaigns get --id 123456789

# 创建广告系列（先用模板生成请求体骨架）
aads campaigns create --template > campaign.json
aads campaigns create --data-file campaign.json

# 更新 / 删除
aads campaigns update --id 123456789 --data '{"name":"新名称"}'
aads campaigns delete --id 123456789    # 高危操作，会要求确认

# 报表
aads reports apps-campaign-reports --data '{"startTime":"2026-07-01","endTime":"2026-07-31"}'

常用参数（所有命令通用）：

| 参数 | 说明 | | --- | --- | | --data '<json>' | 请求体（JSON 字符串） | | --data-file <path> | 请求体（从文件读取） | | --context <值> | X-Ap-Context 头 | | --dry-run | 只打印请求，不发出去 | | --page-all | 查询接口自动翻页合并结果 | | --jq '<路径>' | jq 风格路径过滤输出，如 --jq '.result.userId' | | --raw | 原样输出响应体 | | --yes | 跳过高危写操作的确认提示 |

规范之外或尚未收录的接口，用 api 命令裸调：

aads api GET /v1/me
aads api POST /v1/campaigns/query --data '{"pagination":{"offset":0,"pageSize":100}}'

MCP 服务器

aads mcp 启动一个 MCP stdio server，让支持 MCP 的 AI 客户端（Claude Desktop、Cursor、Codex、WorkBuddy 等）直接操作 Apple Ads——说人话，AI 帮你调 API。

客户端配置：

{
  "mcpServers": {
    "aads": {
      "command": "npx",
      "args": ["@appstare/aads@latest", "mcp"],
      "disabled": false
    }
  }
}

注册的工具包括：

• 认证：auth_login / auth_logout / auth_token / auth_status / auth_list，支持多账号 profile
• 发现：aads_discover（命令目录）、resources（aads://commands、aads://spec）
• 调用：aads_invoke（任意命令）、api（裸调用）
• 高频 typed tools：campaigns / adgroups / keywords / ads / creatives / shared-budgets / negative-keywords / location-groups / recommendations / suggestions / reports / me / search 的常用操作

高危操作必须显式确认，所有工具支持 dry-run 预览。

Shell 补全

source <(aads completion zsh)    # zsh（macOS 默认）
source <(aads completion bash)   # bash

永久生效：把上面那行加进 ~/.zshrc 或 ~/.bashrc。

许可

MIT