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 対応コマンドを設計する前に、バンドルされている App Store Connect エンドポイントのスキーマとリクエスト／クエリフィールドを確認するには、asc schema を使用してください。
  • asc schema --pretty "GET /v1/apps"
  • asc schema --method POST appStoreVersions
• CLI がサポートするワークフロー、部分的にサポートするワークフロー、Web セッションが必要なワークフロー、公開 API では制限されるワークフローの範囲を説明するには、asc capabilities を使用してください。
  • 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 に対応するネイティブの読み取りでは、関連レコードをリレーションごとにリクエストするのではなく、1 回の呼び出しで取得するために --include を使用してください。関連リソースを included 配列で確認するには、--output json を使用してください。
  • 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）

• ドキュメントや自動化では、読み取り専用コマンドにおいて、旧式の get エイリアスより view を優先してください。
  • 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-submission の代わりに --include appStoreVersionSubmission を使用してください。
  • 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"
• 更新のみの edit コマンドを使用する前に、アプリの提供状況を初期設定するには asc pricing availability create を使用してください。Apple が公開 API による初期設定を拒否した場合は、Web セッションで認証して asc web apps availability create を使用するか、App Store Connect で「価格および配信状況」を設定してください。
  • 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 が意図的に上位レベルの置換／設定フローとしてモデル化しており、--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 auth のプロファイルではなく、asc storekit auth login で登録した別のアプリ内課金キーを使用します。
• 権限が不明な場合は、asc web auth capabilities で API キーの権限範囲を正確に確認してください。
  • これはウェブセッション認証の機能です。
  • デフォルトでは現在のローカル認証を確認できます。また、--key-id を指定して特定のキーを確認することもできます。
• キャッシュされた Apple Account のウェブセッションを使って、asc web api-keys create で App Store Connect チーム API キーを作成します。
  • 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 Account のウェブセッション（asc web auth）は別々です。対応している操作では既存のキーチェーン API プロファイルを優先し、ウェブログインを開始する前に asc auth status とコマンドの機能を確認してください。プロファイル名はローカルのラベルであり、アプリレベルの権限境界ではありません。
• ウェブ限定の作業では、まず asc web auth status --apple-id "[email protected]" --output json を確認してください。認証済みのキャッシュ済みセッションを再利用し、変更を加える前に、そのプロバイダーが意図したアカウントと一致することを確認してください。通常の準備としてログアウトしたり、信頼状態やセッション状態をクリアしたりしないでください。
• Apple Account の対話型サインインは、1 つのプロセスだけが担当するようにしてください。コード入力のプロンプトが表示されている間は、同じプロセスを続行してください。チャレンジが無効になる可能性のある別のログインを開始するのではなく、他のエージェントと調整するか、順番に実行してください。
• コードは現在のプロンプトに対応するものを使用してください。信頼済みデバイスの通知コードと SMS の代替コードは、異なる認証手順で使うものです。CLI が電話への送信を通知した後は、先ほどの通知コードではなく、新しく電話に届いたコードを使用してください。通常の再送戦略として、意図的に誤ったコードを送信しないでください。サポートされている復旧方法については、インストール済みコマンドのヘルプを確認してください。
• 失敗した場合は、コードが拒否されたのか、認証またはプロバイダー選択後にタイムアウトしたのかを区別してください。詳細なエラーとインストール済みのバージョンを確認してから、追加のコードをリクエストしてください。リクエストのタイムアウトを延長しても、対話型セッションの問題が解決したことにはなりません。
• ログイン後、別途ステータスを読み取り、authenticated と選択されたプロバイダーを確認してください。成功を報告する前に、次のウェブ操作でキャッシュが再利用されることを確認してください。Apple は後からセッションを期限切れにすることがあるため、永続的な無人認証を約束しないでください。
• サポートされている --two-factor-code-command を設定する前に、asc web auth login --help を確認してください。認証情報やコードをログ、ソース、シェル履歴、PR に含めないでください。CLI にパスワードマネージャーのパスキーを渡せる、あるいはブラウザーでのサインインによってキャッシュが更新されると決めつけず、インストール済みの CLI が明示的にサポートする認証方法だけを使用してください。
• 新規の非対話型ウェブサインインでは、--two-factor-code-command または ASC_WEB_2FA_CODE_COMMAND が必要です。どちらも指定しない場合、パスワードを送信する前に失敗します。キャッシュ済みセッションの再利用に、新たなサインインは必要ありません。
• 公開チーム ID は --public-provider-id で選択してください。--provider-id には Apple の数値のプロバイダー ID を指定します。どちらの ID にも API プロファイル名を代用しないでください。

Apple Ads

• コマンドを選ぶ前に asc ads --help を使用してください。
• Apple Ads では asc ads auth、--ads-profile、ASC_ADS_* 変数を使用します。App Store Connect API の認証情報は使用しません。
• 直接リソースを操作するコマンドは --ad-account または ASC_ADS_AD_ACCOUNT_ID を指定して Platform API v1 を使用します。非推奨の 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 が必要です。明示的に一時停止状態で作成するキャンペーンは、文書化されている主な安全例外です。
• 実環境で変更をテストする場合は、明確なテスト名を付けてリソースを一時停止状態で作成し、すべての ID を保存してください。支出を伴うリソースは先に一時停止し、テストで作成したリソースだけを削除してください。

タイムアウト

• ASC_TIMEOUT / ASC_TIMEOUT_SECONDS はリクエストのタイムアウトを設定します。
• ASC_UPLOAD_TIMEOUT / ASC_UPLOAD_TIMEOUT_SECONDS はアップロードのタイムアウトを設定します。