asc-cli-usage

asc cli 用法

在需要运行或设计 App Store Connect 的 asc 命令时使用此技能。

命令发现

• 始终使用 --help 来发现命令和标志。
  • asc --help
  • asc builds --help
  • asc builds list --help
• 如果你了解工作流但不知道命令路径，请使用 asc search 进行本地、确定性的命令发现。
  • asc search "submit app for review"
  • asc search --output table "upload build"
• 设计面向 API 的命令前，使用 asc schema 检查随附的 App Store Connect 端点架构以及请求和查询字段。
  • asc schema --pretty "GET /v1/apps"
  • asc schema --method POST appStoreVersions
• 使用 asc capabilities 说明 CLI 支持的工作流、部分支持的工作流、基于 Web 会话的工作流，以及受公共 API 限制的工作流覆盖范围。
  • asc capabilities --area release --output table
  • asc capabilities --status web-session --output table
  • asc capabilities --status not-public-api --output markdown

优先使用原生命令，而不是 asc api

• 每次读取和写入都使用原生命令。使用 asc api 前，先通过 asc search "TASK" 或 --help 查找命令。
• 对于支持 --include 的原生读取命令，使用它在一次调用中获取相关记录，而不是针对每种关联分别发起请求。使用 --output json 检查 included 数组中的相关资源。
  • asc versions view --version-id "VERSION_ID" --include build,appStoreVersionSubmission
  • asc builds info --build-id "BUILD_ID" --include buildBetaDetail,betaAppReviewSubmission,betaGroups
  • asc iap view --id "IAP_ID" --include inAppPurchaseLocalizations,appStoreReviewScreenshot
  • asc review submissions-get --id "SUBMISSION_ID" --include items,appStoreVersionForReview
• 单个资源和子项列表读取有各自的命令，例如 asc localizations view --id "LOCALIZATION_ID"、asc testflight groups builds list --group-id "GROUP_ID" 和 asc pricing availability territory-availabilities --app "APP_ID"。
• 仅当没有原生命令能完成任务时，才使用 asc api <METHOD> <PATH>。使用该命令写入时必须加上 --confirm。不要使用 asc auth token 手动编写 curl 请求。

规范动词（当前 asc）

• 在文档和自动化中，对于只读命令，优先使用 view，而不是旧版 get 别名。
  • asc apps view --id "APP_ID"
  • asc versions view --version-id "VERSION_ID" --include build
  • 不加 --include 时，asc versions view 会输出已弃用的摘要；JSON 输出也会在 stderr 上发出警告。请使用 --include build，而不是 --include-build；使用 --include appStoreVersionSubmission，而不是 --include-submission。
  • asc pricing availability view --app "APP_ID"
• 对于仅更新的可用性界面和其他规范编辑流程，优先使用 edit。
  • asc pricing availability edit --app "APP_ID" --territory "USA,GBR" --available true
  • asc app-setup availability edit --app "APP_ID" --territory "USA,GBR" --available true
  • asc xcode version edit --build-number "42"
• 使用 asc pricing availability create 初始化 App 可用性，然后再使用仅支持更新的 edit 命令。如果 Apple 拒绝通过公共 API 进行初始化，请验证 Web 会话身份并使用 asc web apps availability create，或在 App Store Connect 中配置 Pricing and Availability。
  • asc pricing availability create --app "APP_ID" --territory "USA,GBR" --available true --available-in-new-territories true
  • asc web apps availability create --app "APP_ID" --territory "USA,GBR" --available-in-new-territories true
• 如果 CLI 有意将 set 设计为更高级的替换／配置流程，且 --help 仍将 set 显示为规范动词，则继续使用 set。

标志约定

• 使用明确的长标志（例如，--app、--output）。
• 自动化时优先使用明确的标志；某些较新的命令在交互运行时可以提示用户填写缺失字段。
• 破坏性操作需要 --confirm。
• 用户需要获取所有页面时，使用 --paginate。
• 将特定于命令的标志放在叶子子命令之后；父级命令组会拒绝位置不正确的标志。
• 将 --next URL 视为不透明的续接标记。不要将其与新的筛选条件、排序或页面大小标志组合使用；请遵循所选命令帮助中要求的选择器。

输出格式

• 输出默认根据 TTY 状态自动选择：交互式终端中使用 table，通过管道传输或非交互时使用 json。
• 仅在人类可读输出场景中使用 --output table 或 --output markdown。
• --pretty 仅适用于 JSON 输出。
• 除了检查 stdout，也要检查退出状态。批处理操作失败时可能会输出部分回执；重试修改操作前，请检查已完成的操作和资源 ID。

身份验证和默认值

• 优先使用 asc auth login 进行钥匙串身份验证。
• 备用环境变量：ASC_KEY_ID、ASC_ISSUER_ID、ASC_PRIVATE_KEY_PATH、ASC_PRIVATE_KEY、ASC_PRIVATE_KEY_B64。
• ASC_APP_ID 可用于提供默认应用 ID。
• App Store Server API 读取操作（交易、订阅状态、退款、通知历史记录）位于 asc storekit 下，并使用通过 asc storekit auth login 注册的独立应用内购买密钥，而非 asc auth 配置文件。
• 权限不明确时，通过 asc web auth capabilities 检查 API 密钥的具体角色权限。
  • 此功能属于 Web 会话身份验证接口。
  • 默认情况下，它可以解析当前本地身份验证；也可以使用 --key-id 检查指定密钥。
• 通过缓存的 Apple Account Web 会话创建 App Store Connect 团队 API 密钥，使用 asc web api-keys create。
  • 需要 Account Holder 或 Admin 会话；必要时，先使用 asc web auth login --apple-id "[email protected]"。
  • 命令会将一次性 P8 保存为 AuthKey_<KEY_ID>.p8，不会打印其内容；请使用 --output-dir 指定私有目录。
  • 示例：asc web api-keys create --name "CI uploads" --role APP_MANAGER --output-dir "./keys" --output json。

在请求另一个验证码前复用身份验证

• API 密钥身份验证（asc auth）和 Apple 账户 Web 会话（asc web auth）彼此独立。对于受支持的操作，优先使用现有的钥匙串 API 配置；开始 Web 登录前，先检查 asc auth status 和命令功能。配置名称只是本地标签，并非应用级权限边界。
• 对于仅限 Web 的工作，先检查 asc web auth status --apple-id "[email protected]" --output json。复用已通过身份验证的缓存会话，并在执行变更前确认其提供商与预期账户一致。不要把登出或清除信任／会话状态当作常规准备步骤。
• 对于一个 Apple 账户的交互式登录，只让一个进程负责。当验证码提示待处理时，继续使用同一进程；应协调其他 Agent 或将其操作串行化，而不是启动可能使当前验证挑战失效的另一次登录。
• 输入与当前提示对应的验证码。受信任设备通知中的验证码和短信备用验证码属于不同的验证步骤。CLI 提示已向手机发送验证码后，请使用新收到的手机验证码，而不是先前通知中的验证码。不要把故意提交错误验证码当作常规的重新发送策略；请查看已安装命令的帮助，了解受支持的恢复方式。
• 失败时，应区分验证码被拒绝与验证或提供商选择完成后发生超时的情况。查看具体错误和已安装的版本，再请求更多验证码。增加请求超时时间并不能证明交互式会话问题已解决。
• 登录后，通过单独读取状态来确认 authenticated 和所选提供商；报告成功前，确认下一项 Web 操作会复用缓存。Apple 之后可能会使会话过期，因此不要承诺可以永久无人值守地完成身份验证。
• 配置受支持的 --two-factor-code-command 前，请先查看 asc web auth login --help。不要将凭据和验证码写入日志、源代码、shell 历史记录或 PR。不要假设可以将密码管理器的通行密钥提供给 CLI，也不要假设浏览器登录会刷新其缓存；只能使用已安装 CLI 明确支持的身份验证机制。
• 新的非交互式 Web 登录需要 --two-factor-code-command 或 ASC_WEB_2FA_CODE_COMMAND；如果没有提供其中之一，登录会在发送密码前失败。复用缓存会话无需重新登录。
• 使用 --public-provider-id 选择公开团队 ID；--provider-id 接受 Apple 的数字提供商 ID。不要用 API 配置名称替代这两种 ID。

Apple Ads

• 选择命令前，请先使用 asc ads --help。
• Apple Ads 使用 asc ads auth、--ads-profile 和 ASC_ADS_* 变量。它不使用 App Store Connect API 凭据。
• 直接资源命令使用 Platform API v1，并通过 --ad-account 或 ASC_ADS_AD_ACCOUNT_ID 指定广告账户。已弃用的 Campaign Management API v5 命令位于 asc ads v5 下，并使用 --org 或 ASC_ADS_ORG_ID；切勿将两种 ID 混用。
• 使用 asc ads auth discover --output json 查找广告账户访问权限，或使用 asc ads acls list --output json 查看单个 ACL 响应。
• 请求体命令使用 --file，文件内容必须符合叶级帮助中指定的确切架构。V1 查询筛选器使用单数形式的 value，批量请求体可能使用包装对象，而不是 v5 数组。
• Apple Ads 资源命令会输出 JSON。仅在帮助中注明支持的位置使用 --paginate；报告和大多数查询请求体会在 JSON 文件中携带分页参数。
• 删除以及涉及支出、账单、投放、定向或访问权限的变更都需要 --confirm。明确创建为暂停状态的 Campaign 是文档中主要的安全例外。
• 执行实时变更测试时，创建名称清晰的暂停资源，保存每个 ID，优先暂停会产生支出的资源，并且只删除测试创建的资源。

超时

• ASC_TIMEOUT / ASC_TIMEOUT_SECONDS 控制请求超时。
• ASC_UPLOAD_TIMEOUT / ASC_UPLOAD_TIMEOUT_SECONDS 控制上传超时。