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"
• 使用 asc schema 检查捆绑的 App Store Connect 端点模式和请求/查询字段，然后再设计面向 API 的命令。
  • 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）

• 在文档和自动化中，对于只读命令，优先使用 view 而不是旧的 get 别名。
  • asc apps view --id "APP_ID"
  • asc versions view --version-id "VERSION_ID"
  • 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 初始化应用可用性，然后再使用仅更新的 edit 命令。
  • asc pricing availability create --app "APP_ID" --territory "USA,GBR" --available true --available-in-new-territories true
• 当 CLI 有意建模更高级别的替换/配置流程，并且 --help 仍显示 set 作为规范动词时，保留 set。

标志约定

• 使用显式的长标志（例如 --app、--output）。
• 在自动化中优先使用显式标志；某些较新的命令在交互式运行时可以提示缺失的字段。
• 破坏性操作需要 --confirm。
• 当用户想要所有页面时，使用 --paginate。

输出格式

• 输出默认值根据 TTY 感知：在交互式终端中为 table，在管道或非交互式环境中为 json。
• 仅当需要人类可读的输出时，才使用 --output table 或 --output markdown。
• --pretty 仅对 JSON 输出有效。

认证和默认值

• 优先通过 asc auth login 使用密钥链认证。
• 后备环境变量：ASC_KEY_ID、ASC_ISSUER_ID、ASC_PRIVATE_KEY_PATH、ASC_PRIVATE_KEY、ASC_PRIVATE_KEY_B64。
• ASC_APP_ID 可以提供默认的应用 ID。
• 当权限不明确时，使用 asc web auth capabilities 检查确切的 API 密钥角色覆盖范围。
  • 此命令位于 Web 会话认证界面下。
  • 默认情况下可以解析当前的本地认证，或者使用 --key-id 检查特定密钥。

Apple Ads

• 在选择命令之前，使用 asc ads --help。
• Apple Ads 使用 asc ads auth、--ads-profile 和 ASC_ADS_* 变量。它不使用 App Store Connect API 凭据。
• 使用 asc ads acls --output json 解析组织访问权限，除非组织 ID 已知。
• 大多数端点命令需要 --org 或 ASC_ADS_ORG_ID。
• 正文命令使用 --file 和 Apple Ads JSON 负载。对象端点需要 JSON 对象。批量端点通常需要 JSON 数组。
• 仅在帮助显示支持的地方使用 --paginate。报告和选择器负载在 JSON 文件内部携带分页信息。
• 破坏性命令和批量删除命令需要 --confirm。
• 对于实时变更测试，使用清晰的测试名称创建暂停的资源，并在完成后删除父级广告系列。

超时

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