App Store Connect CLI 使用教程：用命令行自动化 iOS 应用发布、TestFlight 与元数据管理

大家好，这里是「代码简单说」。

如果平时需要维护 iOS、macOS、tvOS 或 visionOS 项目，很多 App Store Connect 操作都需要在网页后台完成，例如上传构建版本、管理 TestFlight、查看崩溃、修改应用元数据、提交审核等。

今天介绍一个比较实用的开源工具：App Store Connect CLI，命令行名称为 asc。

它是一个面向 Apple App Store Connect API 的轻量级 CLI，可以把很多原本需要手动操作的流程转变为命令行脚本，并进一步接入 CI/CD 和 AI Agent 工作流。

项目定位就是一个“快速、轻量、可脚本化”的 App Store Connect CLI，可用于自动化 iOS、macOS、tvOS 和 visionOS 发布流程。

项目 GitHub：

https://github.com/rorkai/App-Store-Connect-CLI

项目采用 MIT License，同时支持 Homebrew。

---

一、App Store Connect CLI 是什么？

App Store Connect CLI 是一个基于 App Store Connect API 的命令行工具，核心命令是：

asc

相比直接使用 App Store Connect 网页后台，CLI 更适合自动化场景。

例如可以直接执行：

asc apps list

查看应用列表。

也可以执行：

asc builds upload

上传 .ipa 或 .pkg。

还可以进一步组合 GitHub Actions、GitLab、Bitrise、CircleCI 等 CI/CD 系统，实现自动发布。

项目本身还提供了一套 Agent Skills，可以让 AI Agent 辅助执行构建、TestFlight、元数据同步、提交审核和签名相关工作。

---

二、为什么需要 App Store Connect CLI？

对于个人开发者来说，偶尔使用 App Store Connect 网页后台没有问题。

但是项目进入持续开发之后，重复操作会越来越多。

例如：

代码提交
   ↓
Xcode 构建
   ↓
生成 IPA
   ↓
上传 App Store Connect
   ↓
等待构建处理
   ↓
加入 TestFlight
   ↓
修改版本信息
   ↓
提交审核

如果这些流程完全依赖手动操作，就比较适合通过脚本自动化。

asc 可以把其中很多环节转化为命令：

asc builds upload
asc builds list
asc testflight groups list
asc publish testflight
asc publish appstore
asc review status

这样就可以把 App Store Connect 纳入完整的 CI/CD 流程。

---

三、安装 App Store Connect CLI

1. macOS 使用 Homebrew

官方文档推荐 Homebrew：

brew install asc

安装完成后检查：

asc version

再运行：

asc --help

如果能够正常显示版本和帮助信息，就说明安装成功。

---

2. macOS / Linux 安装脚本

也可以直接使用官方安装脚本：

curl -fsSL https://asccli.sh/install | bash

安装完成后：

asc version

验证安装结果。

---

3. Windows 安装

Windows 版本可以通过 WinGet 安装：

winget install asc

也可以使用精确的包 ID：

winget install --id Rorkai.ASC --exact

如果 WinGet 中暂时搜索不到对应的简写名称，可以直接前往 GitHub Releases 下载已经编译好的版本。

官方说明中还特别提到，发布的二进制文件是自包含的，不需要额外安装 Go 环境。

安装完成后可以执行：

Get-Command asc
asc version

检查系统是否正确找到 asc。

---

四、配置 App Store Connect API

安装 CLI 只是第一步。

如果需要操作 App Store Connect，还需要配置 Apple API Key。

进入：

https://appstoreconnect.apple.com/access/integrations/api

创建 API Key。

通常需要获得以下信息：

Key ID
Issuer ID
Private Key

然后通过：

asc auth login \
  --name "MyApp" \
  --key-id "ABC123" \
  --issuer-id "DEF456" \
  --private-key /path/to/AuthKey.p8 \
  --network

完成认证。

其中：

--name

用于设置认证配置名称。

--key-id

对应 Apple API Key 的 Key ID。

--issuer-id

对应 Issuer ID。

--private-key

指定 .p8 私钥文件。

---

五、CI/CD 环境如何认证？

如果在 GitHub Actions、GitLab CI 或其他服务器环境中运行，通常没有桌面系统的 Keychain 环境。

这种情况可以使用：

asc auth login \
  --bypass-keychain \
  --name "MyCIKey" \
  --key-id "ABC123" \
  --issuer-id "DEF456" \
  --private-key /path/to/AuthKey.p8

这样就可以绕过系统 Keychain。

配置完成后建议运行：

asc auth status --validate

以及：

asc auth doctor

检查认证是否正常。

---

六、查看 App Store Connect 中的应用

认证完成以后，可以执行：

asc apps list --output table

以表格形式查看应用。

也可以使用 JSON：

asc apps list --output json --pretty

这对于脚本和自动化程序尤其方便。

asc 会根据输出环境自动选择默认格式：

交互式终端 → table
管道、文件、CI → json

也可以手动指定：

asc apps list --output json

或者：

asc apps list --output markdown

---

七、上传 IPA 到 App Store Connect

这是 App Store Connect CLI 最实用的功能之一。

例如：

asc builds upload \
  --app "123456789" \
  --ipa "/path/to/MyApp.ipa"

这里：

--app

是 App Store Connect 中的 App ID。

如果使用 Xcode 导出的 IPA，就可以直接交给 asc 上传。

同时可以查看构建：

asc builds list \
  --app "123456789" \
  --output table

这样就能快速确认构建是否已经进入 App Store Connect。

---

八、macOS 应用如何上传 PKG？

如果是 macOS 应用，可以上传 .pkg。

例如：

asc builds upload \
  --app "123456789" \
  --pkg "./build/MyMacApp.pkg" \
  --version "1.2.3" \
  --build-number "42" \
  --wait \
  --output json

等待构建处理完成后，还可以将版本加入 TestFlight Beta Group：

asc builds add-groups \
  --app "123456789" \
  --build-number "42" \
  --version "1.2.3" \
  --platform MAC_OS \
  --group "Internal Testers"

官方文档也提醒，如果使用 Xcode 本地构建相关参数，需要正确指定 workspace/project 和 scheme；如果已经有导出的 .ipa 或 .pkg，则可以直接上传。

---

九、TestFlight 自动化

TestFlight 也是日常开发中经常需要操作的地方。

例如查看 TestFlight 反馈：

asc testflight feedback list \
  --app "123456789" \
  --paginate

查看最近的崩溃：

asc testflight crashes list \
  --app "123456789" \
  --sort -createdDate \
  --limit 10

查看指定提交的崩溃日志：

asc testflight crashes log \
  --submission-id "SUBMISSION_ID"

这些操作都可以直接从终端执行。

---

十、TestFlight 发布

如果项目已经准备进入 TestFlight，可以使用发布命令。

例如：

asc publish testflight \
  --group "Internal Testers" \
  --wait

对于外部测试组，如果需要提交 Beta App Review，可以增加：

--submit --confirm

这样就能够进一步把发布流程脚本化。

---

十一、自动发布 App Store

除了 TestFlight，还可以直接执行 App Store 发布流程。

例如：

asc publish appstore \
  --app "123456789" \
  --ipa "/path/to/MyApp.ipa" \
  --version "1.2.3" \
  --submit \
  --confirm

之后可以查看提交状态：

asc status \
  --app "123456789" \
  --watch

在正式发布之前，也可以先进行准备检查：

asc validate \
  --app "123456789" \
  --version "1.2.3"

如果需要查看审核状态：

asc review status \
  --app "123456789"

或者：

asc review doctor \
  --app "123456789"

---

十二、自动管理 App Store 元数据

对于有多个语言版本的 App，手动修改标题、副标题、关键词和描述非常麻烦。

asc 支持 metadata 工作流。

初始化本地 metadata：

asc metadata init \
  --dir "./metadata" \
  --version "1.2.3" \
  --locale "en-US"

应用 metadata：

asc metadata apply \
  --app "123456789" \
  --version "1.2.3" \
  --dir "./metadata" \
  --dry-run

还可以进行关键词审计：

asc metadata keywords audit \
  --app "123456789" \
  --version "1.2.3" \
  --blocked-terms-file "./blocked-terms.txt"

官方说明中，这个关键词审计命令可以检查重复短语、不同语言之间的重复词、与 App 名称或副标题的重叠，以及关键词字节预算等。

这意味着 ASO 内容也可以纳入版本管理。

---

十三、自动上传截图

除了文字元数据，截图同样可以通过命令行管理。

先生成截图计划：

asc screenshots plan \
  --app "123456789" \
  --version "1.2.3" \
  --review-output-dir "./screenshots/review"

确认以后执行：

asc screenshots apply \
  --app "123456789" \
  --version "1.2.3" \
  --review-output-dir "./screenshots/review" \
  --confirm

也可以查看指定本地化版本的截图：

asc screenshots list \
  --version-localization "VERSION_LOCALIZATION_ID"

上传某个语言版本的截图：

asc screenshots upload \
  --version-localization "VERSION_LOCALIZATION_ID" \
  --path "./screenshots/en-US" \
  --device-type "IPHONE_65" \
  --replace \
  --max-screenshots 10

需要注意：

VERSION_LOCALIZATION_ID 是 App Store 版本本地化资源 ID，不是 en-US 这样的 locale 字符串。

---

十四、证书、Profiles 与 Bundle ID

开发者经常还需要查看签名相关资源。

例如：

asc certificates list

查看 Profiles：

asc profiles list

查看 Bundle ID：

asc bundle-ids list

这样可以把部分开发者账号资源管理操作也纳入 CLI。

---

十五、AI Agent Skills

这个项目比较有意思的一点，是它不仅仅是传统 CLI，还提供了：

Agent Skills

项目提供：

app-store-connect-cli-skills

可以用于自动化：

Build
TestFlight
Metadata
Submission
Signing

安装方式非常简单：

asc install-skills

官方说明显示，该命令会安装经过审核并固定到指定 commit 的 23 个 Skills，并验证安装内容，同时尽量避免影响其他已有 Skills。

对于现在越来越多的 AI Coding Agent 来说，这个方向值得关注。

传统 CLI 主要解决：

开发者 → CLI → App Store Connect

而 Agent Skills 可以进一步变成：

开发者
   ↓
AI Agent
   ↓
App Store Connect CLI
   ↓
App Store Connect

例如未来可以直接让 Agent 完成：

构建项目
↓
检查版本号
↓
上传 IPA
↓
查看构建状态
↓
加入 TestFlight
↓
检查审核状态

这比单纯让 AI 修改代码更加接近完整的软件交付流程。

---

十六、工作流自动化

asc 还提供 workflow 机制。

检查 workflow：

asc workflow validate --output json

模拟执行：

asc workflow run \
  --dry-run \
  testflight_beta \
  VERSION:1.2.3

如果确认无误，再执行：

asc workflow run \
  testflight_beta \
  VERSION:1.2.3

项目还提供了从本地 Xcode 编译到 TestFlight 的完整 workflow 示例，可以结合：

asc xcode build
asc xcode inject
asc xcode archive
asc xcode export
asc publish testflight

组成完整的自动化发布链路。

---

十七、Xcode Cloud 也可以管理

如果项目使用 Xcode Cloud，同样可以通过命令行触发构建。

例如：

asc xcode-cloud run \
  --workflow-id "WORKFLOW_ID" \
  --pull-request-id "PR_ID"

也可以基于已有 Build Run 重新执行：

asc xcode-cloud run \
  --source-run-id "BUILD_RUN_ID" \
  --clean

查看指定构建：

asc xcode-cloud build-runs get \
  --id "BUILD_RUN_ID"

这样 CI/CD 就能够进一步和 Xcode Cloud 打通。

---

十八、Apple Ads 也可以通过 CLI 管理

这个项目不仅覆盖 App Store Connect，还提供 Apple Ads 相关命令。

例如登录：

asc ads auth login \
  --name "Marketing" \
  --client-id "SEARCHADS_CLIENT_ID" \
  --team-id "SEARCHADS_TEAM_ID" \
  --key-id "KEY_ID" \
  --private-key ./ads-key.pem \
  --ad-account "987654"

查询广告活动：

asc ads campaigns find \
  --ad-account "987654" \
  --file query.json \
  --output json

查看报告：

asc ads reports apps campaigns \
  --ad-account "987654" \
  --file report.json \
  --output json

需要注意，Apple Ads 使用独立的 OAuth 凭据，并不是普通 App Store Connect API 凭据。

---

十九、StoreKit Retention Messaging

项目还包含 StoreKit Retention Messaging 相关能力。

例如：

asc storekit auth login \
  --name Production \
  --key-id "KEY_ID" \
  --issuer-id "ISSUER_ID" \
  --private-key ./SubscriptionKey.p8 \
  --bundle-id com.example.app

检查环境：

asc storekit auth doctor \
  --environment sandbox \
  --network

查看消息：

asc storekit retention-messaging messages list \
  --environment sandbox \
  --output json

查看生产环境 endpoint：

asc storekit retention-messaging endpoint view \
  --environment production

这部分适合涉及订阅和用户留存场景的应用。

---

二十、如何查看命令帮助？

如果不知道某个命令具体有哪些参数，不需要专门查网页。

直接运行：

asc --help

查看一级命令。

例如：

asc builds --help

继续查看子命令：

asc builds upload --help

官方将内置 help 作为命令和参数的权威来源。

推荐形成这样的使用习惯：

asc <command> --help

先查看实际支持的参数，再写自动化脚本。

---

二十一、Telemetry 隐私问题

使用 CLI 时，还有一个比较容易忽略的问题：Telemetry。

项目默认会发送匿名的命令级使用统计，用于帮助维护者了解命令使用情况和可靠性。

根据项目文档，Telemetry 可能包含：

CLI 版本
操作系统
CPU 架构
命令路径
执行耗时
运行环境
结果类别
API HTTP 状态码

但不会发送：

命令原始参数
stderr
错误消息
Flag 的具体值
API Response Body
账号密码
Private Key
Apple Account
Team ID
Issuer ID
App ID
Bundle ID
用户名
主机名
仓库名称
文件路径

查看状态：

asc telemetry status

关闭：

asc telemetry disable

重置安装 ID：

asc telemetry reset-id

也可以设置：

ASC_TELEMETRY_DISABLED=1

或者：

DO_NOT_TRACK=1

来关闭 Telemetry。

---

二十二、一个完整的自动发布思路

如果自己维护一个 iOS 项目，可以把整个流程整理成：

Git Push
   ↓
CI/CD
   ↓
Xcode Build
   ↓
生成 IPA
   ↓
asc builds upload
   ↓
等待 App Store Connect 处理
   ↓
asc builds add-groups
   ↓
TestFlight
   ↓
测试
   ↓
asc validate
   ↓
asc publish appstore
   ↓
App Store Review

进一步还可以加入：

Metadata
截图
ASO Keywords
Review Status
Crash Logs

最终形成一套完整的 App Store Connect 自动化系统。

---

二十三、适合哪些开发者？

这个工具最适合以下几类场景。

1. iOS 独立开发者

如果经常自己发布 App，可以减少重复性的网页操作。

2. 团队开发

可以把发布流程标准化，不再依赖某个开发者手动操作后台。

3. CI/CD

例如：

GitHub Actions
GitLab CI
Bitrise
CircleCI

都可以调用 CLI。

4. AI Coding Agent

这是我认为这个项目比较值得关注的方向。

尤其是项目同时提供 Agent Skills 之后，AI Agent 不再只负责：

写代码

而是可以进一步参与：

构建
测试
发布
TestFlight
App Store Connect

从“AI 编程”进一步向“AI 软件交付”发展。

---

二十四、总结

App Store Connect CLI 本质上是把大量 App Store Connect 操作从网页后台搬到了命令行。

核心命令可以简单理解为：

asc apps
asc builds
asc testflight
asc metadata
asc screenshots
asc certificates
asc profiles
asc bundle-ids
asc workflow
asc publish
asc review

对于偶尔发布一次 App 的开发者来说，它可能只是一个方便的命令行工具。

但对于需要持续交付、CI/CD 自动化以及 AI Agent 工作流的开发团队来说，价值会明显更高。

尤其是：

asc install-skills

把 App Store Connect 能力进一步暴露给 Agent 后，可以探索让 AI Agent 参与完整的 iOS 应用交付流程。

项目 GitHub：

https://github.com/rorkai/App-Store-Connect-CLI

需要注意的是，该项目明确声明自己是独立的非官方工具，与 Apple Inc. 没有隶属、背书或赞助关系；App Store Connect、TestFlight、Xcode Cloud 等名称属于 Apple 的商标。