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 支援、部分支援、網路工作階段以及僅限公開 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。

輸出格式

• 輸出預設會感知終端機：在互動終端機中使用 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 金鑰角色涵蓋範圍。
  • 此功能位於網路工作階段驗證介面下。
  • 預設可解析目前的本機驗證，或使用 --key-id 檢查特定金鑰。

Apple Ads

• 在選擇指令前，先使用 asc ads --help。
• Apple Ads 使用 asc ads auth、--ads-profile 以及 ASC_ADS_* 變數。它不使用 App Store Connect API 憑證。
• 除非組織 ID 已知，否則使用 asc ads acls --output json 解析組織存取權限。
• 大多數端點指令需要 --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 控制上傳逾時。