@onmyway133/asc-cli 1.0.1

package/src/index.ts

@@ -0,0 +1,1661 @@
+#!/usr/bin/env bun
+/**
+ * asc — App Store Connect CLI
+ *
+ * AUTHENTICATION: All API commands require a configured profile.
+ * Run `asc auth login` first to set up credentials.
+ *
+ * GETTING IDs: Most commands require resource IDs (app IDs, build IDs, etc.).
+ * Use listing commands to discover IDs before using detail/update commands:
+ *   asc apps list              → get App IDs
+ *   asc builds list            → get Build IDs
+ *   asc versions list          → get Version IDs
+ *   asc testflight groups list → get Group IDs
+ *
+ * OUTPUT FORMATS:
+ *   --output table  (default when stdout is a TTY)
+ *   --output json   (default when stdout is piped — use for programmatic access)
+ *
+ * WHEN APPLE UPDATES THEIR API:
+ *   bun run generate  → re-generates src/api/generated/ from the latest OpenAPI spec
+ */
+
+import { defineCommand, runMain } from "citty"
+import { printError } from "./utils/output.ts"
+import { buildHelpDocument } from "./utils/help-spec.ts"
+import pkg from "../package.json"
+
+// ---- Auth commands ----
+import { authLogin, authList, authLogout, authStatus, authUse, profileView, profileUpdate, profileDelete as authProfileDelete } from "./commands/auth.ts"
+
+// ---- App commands ----
+import { appsList, appsGet } from "./commands/apps.ts"
+
+// ---- Builds ----
+import { buildsList, buildsGet, buildsUpdateBetaNotes } from "./commands/builds.ts"
+
+// ---- Versions ----
+import { versionsList, versionsCreate, versionsSubmit } from "./commands/versions.ts"
+
+// ---- TestFlight ----
+import {
+  testflightGroupsList,
+  testflightTestersList,
+  testflightTestersAdd,
+  testflightTestersRemove,
+} from "./commands/testflight.ts"
+
+// ---- Metadata ----
+import { metadataList, metadataUpdate } from "./commands/metadata.ts"
+
+// ---- Reviews ----
+import { reviewsList, reviewsGet, reviewsRespond } from "./commands/reviews.ts"
+
+// ---- Pricing ----
+import { pricingScheduleGet, pricingScheduleSet, pricingPointsList, territoriesList } from "./commands/pricing.ts"
+
+// ---- Availability ----
+import { availabilityGet, availabilityTerritoriesSet } from "./commands/availability.ts"
+
+// ---- IAP ----
+import { iapList, iapGet, iapCreate, iapDelete } from "./commands/iap.ts"
+
+// ---- Subscriptions ----
+import {
+  subscriptionGroupsList,
+  subscriptionGroupCreate,
+  subscriptionsList,
+  subscriptionGet,
+  subscriptionCreate,
+  subscriptionPricesList,
+} from "./commands/subscriptions.ts"
+
+// ---- App Info ----
+import { appInfoGet, appInfoUpdate, appCategoriesList, ageRatingDeclarationUpdate } from "./commands/app-info.ts"
+
+// ---- Screenshots ----
+import {
+  screenshotSetsList,
+  screenshotsList,
+  screenshotCreate,
+  screenshotDelete,
+  previewSetsList,
+} from "./commands/screenshots.ts"
+
+// ---- Signing ----
+import {
+  certificatesList,
+  certificateGet,
+  certificateRevoke,
+  devicesList,
+  deviceRegister,
+  bundleIdsList,
+  bundleIdRegister,
+  profilesList,
+  profileDelete,
+} from "./commands/signing.ts"
+
+// ---- Reports ----
+import { salesReportDownload, financeReportDownload, analyticsReportsList, analyticsReportRequest } from "./commands/reports.ts"
+
+// ---- Xcode Cloud ----
+import {
+  xcodeCloudProductsList,
+  workflowsList,
+  workflowGet,
+  xcodeCloudBuildsList,
+  xcodeCloudBuildRun,
+  xcodeCloudArtifactsList,
+  xcodeCloudTestResultsList,
+} from "./commands/xcode-cloud.ts"
+
+// ---- Game Center ----
+import {
+  achievementsList,
+  achievementGet,
+  leaderboardsList,
+  leaderboardSetsList,
+} from "./commands/game-center.ts"
+
+// ---- Beta Review ----
+import {
+  betaReviewSubmissionCreate,
+  betaReviewSubmissionGet,
+  betaReviewDetailGet,
+  betaReviewDetailUpdate,
+  buildBetaDetailUpdate,
+  betaBuildLocalizationsList,
+} from "./commands/beta-review.ts"
+
+// =============================================================================
+// AUTH
+// =============================================================================
+
+const authLoginCmd = defineCommand({
+  meta: {
+    name: "login",
+    description: [
+      "Add or update an authentication profile.",
+      "Stores API key credentials for use with all other commands.",
+      "Credentials are saved to ~/.asc/credentials.json with the private key",
+      "stored in macOS Keychain (or as a file path if --bypass-keychain is set).",
+      "",
+      "To create an API key: App Store Connect → Users → Keys → Generate API Key.",
+      "Download the .p8 file (you can only download it once).",
+      "",
+      "Examples:",
+      "  asc auth login --key-id ABC123 --issuer-id 12345678-... --private-key ~/Downloads/AuthKey_ABC123.p8",
+      "  asc auth login --name work --key-id ABC123 --issuer-id 12345678-... --private-key ~/keys/work.p8",
+    ].join("\n"),
+  },
+  args: {
+    name: { type: "string", alias: "n", description: "Profile name to save as. Defaults to 'default'. Use --name to manage multiple accounts." },
+    "key-id": { type: "string", alias: "k", description: "10-character API Key ID from App Store Connect → Users → Keys" },
+    "issuer-id": { type: "string", alias: "i", description: "Issuer ID (UUID) from App Store Connect → Users → Keys" },
+    "private-key": { type: "string", alias: "p", description: "Path to the downloaded .p8 private key file" },
+    "bypass-keychain": { type: "boolean", description: "Skip macOS Keychain — store private key path in credentials.json instead" },
+  },
+  async run({ args }) {
+    await authLogin({
+      name: args["name"],
+      keyId: args["key-id"],
+      issuerId: args["issuer-id"],
+      privateKey: args["private-key"],
+      bypassKeychain: args["bypass-keychain"],
+    })
+  },
+})
+
+const authListCmd = defineCommand({
+  meta: { name: "list", description: "List all saved authentication profiles. Shows profile names, key IDs, and which is active." },
+  run() { authList() },
+})
+
+const authUseCmd = defineCommand({
+  meta: {
+    name: "use",
+    description: "Switch the active authentication profile. All subsequent API calls will use this profile's credentials.",
+  },
+  args: { name: { type: "positional", description: "Profile name to activate (see: asc auth list)", required: false } },
+  async run({ args }) { await authUse(args.name) },
+})
+
+const authStatusCmd = defineCommand({
+  meta: {
+    name: "status",
+    description: "Show the current active profile. Use --validate to test credentials by generating a JWT and making an API call.",
+  },
+  args: { validate: { type: "boolean", description: "Generate a JWT token and validate it against the API" } },
+  async run({ args }) { await authStatus({ validate: args.validate }) },
+})
+
+const authLogoutCmd = defineCommand({
+  meta: { name: "logout", description: "Remove a profile from ~/.asc/credentials.json and delete its key from Keychain." },
+  args: { name: { type: "string", alias: "n", description: "Profile name to remove. Omit to remove the active profile." } },
+  async run({ args }) { await authLogout(args.name) },
+})
+
+const profileViewCmd = defineCommand({
+  meta: {
+    name: "view",
+    description: "Show all details for a profile (key ID, issuer ID, keychain status).",
+  },
+  args: {
+    name: { type: "positional", description: "Profile name. Omit for the active profile. Use: asc auth list", required: false },
+  },
+  run({ args }) { profileView(args.name) },
+})
+
+const profileUpdateCmd = defineCommand({
+  meta: {
+    name: "update",
+    description: [
+      "Update fields on an existing profile without re-running the full login flow.",
+      "Only the flags you provide will be changed.",
+      "Omit the profile name to update the active profile.",
+    ].join("\n"),
+  },
+  args: {
+    name: { type: "positional", description: "Profile name to update. Omit for active profile.", required: false },
+    "key-id": { type: "string", description: "New API Key ID" },
+    "issuer-id": { type: "string", description: "New Issuer ID (UUID)" },
+    "private-key": { type: "string", description: "Path to new .p8 private key file" },
+    "vendor-number": { type: "string", description: "Vendor number for sales/finance reports" },
+    "bypass-keychain": { type: "boolean", description: "Store key path in file instead of Keychain" },
+    rename: { type: "string", description: "Rename the profile to a new name" },
+  },
+  async run({ args }) {
+    await profileUpdate(args.name, {
+      keyId: args["key-id"],
+      issuerId: args["issuer-id"],
+      privateKey: args["private-key"],
+      vendorNumber: args["vendor-number"],
+      bypassKeychain: args["bypass-keychain"],
+      renameTo: args["rename"],
+    })
+  },
+})
+
+const profileDeleteCmd = defineCommand({
+  meta: {
+    name: "delete",
+    description: "Remove a profile and delete its private key from Keychain.",
+  },
+  args: {
+    name: { type: "positional", description: "Profile name to delete. Use: asc auth list", required: false },
+  },
+  async run({ args }) { await authProfileDelete(args.name) },
+})
+
+const profileCmd = defineCommand({
+  meta: {
+    name: "profile",
+    description: [
+      "Manage individual authentication profiles.",
+      "Use 'asc auth list' to see all profiles.",
+      "Use --profile <name> on any command to use a specific profile.",
+    ].join("\n"),
+  },
+  subCommands: {
+    view: profileViewCmd,
+    update: profileUpdateCmd,
+    delete: profileDeleteCmd,
+  },
+})
+
+
+const authCmd = defineCommand({
+  meta: {
+    name: "auth",
+    description: [
+      "Manage App Store Connect API authentication profiles.",
+      "Profiles store key ID, issuer ID, and private key path/content.",
+      "Multiple profiles allow switching between developer accounts.",
+      "Use 'asc auth login' to get started.",
+    ].join("\n"),
+  },
+  subCommands: { login: authLoginCmd, list: authListCmd, use: authUseCmd, status: authStatusCmd, logout: authLogoutCmd, profile: profileCmd },
+})
+
+// =============================================================================
+// APPS
+// =============================================================================
+
+const appsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List all apps in your App Store Connect account.",
+      "Returns App IDs needed by most other commands.",
+      "Use --output json for programmatic access.",
+    ].join("\n"),
+  },
+  args: {
+    limit: { type: "string", description: "Maximum number of apps to return (default: all)" },
+    output: { type: "string", alias: "o", description: "Output format: table (default in TTY) | json (default when piped)" },
+  },
+  async run({ args }) {
+    await appsList({ limit: args.limit ? Number(args.limit) : undefined, output: args.output })
+  },
+})
+
+const appsGetCmd = defineCommand({
+  meta: {
+    name: "get",
+    description: [
+      "Get detailed information about a specific app.",
+      "Use 'asc apps list' to find the App ID.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "positional", description: "App ID (numeric string, e.g. '1234567890'). Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await appsGet(args["app-id"], { output: args.output }) },
+})
+
+const appsCmd = defineCommand({
+  meta: {
+    name: "apps",
+    description: "List and inspect apps in your account. App IDs are required by most other commands.",
+  },
+  subCommands: { list: appsListCmd, get: appsGetCmd },
+})
+
+// =============================================================================
+// BUILDS
+// =============================================================================
+
+const buildsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List builds uploaded to App Store Connect.",
+      "Builds are created by uploading via Xcode, Instruments, or Transporter.",
+      "Use --app-id to filter by app. Build IDs are needed by testflight and beta-review commands.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "Filter by App ID. Use: asc apps list" },
+    version: { type: "string", description: "Filter by version string (e.g. '2.0.1')" },
+    platform: { type: "string", description: "Filter by platform: IOS | MAC_OS | TV_OS | VISION_OS" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) {
+    await buildsList({ appId: args["app-id"], version: args.version, platform: args.platform, output: args.output })
+  },
+})
+
+const buildsGetCmd = defineCommand({
+  meta: {
+    name: "get",
+    description: "Get full details for a specific build including processing state and expiry date.",
+  },
+  args: {
+    "build-id": { type: "positional", description: "Build ID (UUID). Use: asc builds list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await buildsGet(args["build-id"], { output: args.output }) },
+})
+
+const buildsUpdateBetaNotesCmd = defineCommand({
+  meta: {
+    name: "update-beta-notes",
+    description: [
+      "Set or update the TestFlight 'What to Test' notes for a build.",
+      "These notes are shown to testers when they receive the build.",
+    ].join("\n"),
+  },
+  args: {
+    "build-id": { type: "string", description: "Build ID (UUID). Use: asc builds list", required: true },
+    locale: { type: "string", description: "Locale code, e.g. 'en-US', 'ja', 'fr-FR'", required: true },
+    notes: { type: "string", description: "What to test text (max 4000 characters)", required: true },
+  },
+  async run({ args }) {
+    await buildsUpdateBetaNotes({ buildId: args["build-id"], locale: args.locale, notes: args.notes })
+  },
+})
+
+const buildsCmd = defineCommand({
+  meta: {
+    name: "builds",
+    description: "Manage app builds. Builds are uploaded via Xcode or Transporter and used for TestFlight and App Store submission.",
+  },
+  subCommands: { list: buildsListCmd, get: buildsGetCmd, "update-beta-notes": buildsUpdateBetaNotesCmd },
+})
+
+// =============================================================================
+// VERSIONS
+// =============================================================================
+
+const versionsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List App Store versions for an app.",
+      "Each version has an ID used by metadata, screenshots, and submission commands.",
+      "States: PREPARE_FOR_SUBMISSION, WAITING_FOR_REVIEW, IN_REVIEW, READY_FOR_SALE, etc.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    platform: { type: "string", description: "Filter by platform: IOS | MAC_OS | TV_OS | VISION_OS" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) {
+    await versionsList({ appId: args["app-id"], platform: args.platform, output: args.output })
+  },
+})
+
+const versionsCreateCmd = defineCommand({
+  meta: {
+    name: "create",
+    description: [
+      "Create a new App Store version record.",
+      "This creates the version container for metadata, screenshots, and submission.",
+      "Increment the version string from the previous release.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    version: { type: "string", description: "Version string in MAJOR.MINOR.PATCH format, e.g. '2.1.0'", required: true },
+    platform: { type: "string", description: "Platform: IOS (default) | MAC_OS | TV_OS | VISION_OS", default: "IOS" },
+  },
+  async run({ args }) {
+    await versionsCreate({ appId: args["app-id"], version: args.version, platform: args.platform })
+  },
+})
+
+const versionsSubmitCmd = defineCommand({
+  meta: {
+    name: "submit",
+    description: [
+      "Submit an App Store version for App Review.",
+      "Prerequisites: metadata is complete, screenshots are uploaded, binary is attached.",
+      "Use 'asc versions list' to find the Version ID.",
+    ].join("\n"),
+  },
+  args: { "version-id": { type: "positional", description: "Version ID (UUID). Use: asc versions list --app-id <id>", required: true } },
+  async run({ args }) { await versionsSubmit(args["version-id"]) },
+})
+
+const versionsCmd = defineCommand({
+  meta: {
+    name: "versions",
+    description: "Manage App Store version records. Versions hold metadata, screenshots, and track review state.",
+  },
+  subCommands: { list: versionsListCmd, create: versionsCreateCmd, submit: versionsSubmitCmd },
+})
+
+// =============================================================================
+// TESTFLIGHT
+// =============================================================================
+
+const tfGroupsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List all TestFlight beta groups. Groups control which testers get access to builds. Use Group IDs to manage testers.",
+  },
+  args: {
+    "app-id": { type: "string", description: "Filter by App ID. Use: asc apps list" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await testflightGroupsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const tfGroupsCmd = defineCommand({
+  meta: { name: "groups", description: "Manage TestFlight beta groups (tester groups)" },
+  subCommands: { list: tfGroupsListCmd },
+})
+
+const tfTestersListCmd = defineCommand({
+  meta: { name: "list", description: "List all testers in a TestFlight group." },
+  args: {
+    "group-id": { type: "string", description: "Beta Group ID. Use: asc testflight groups list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await testflightTestersList({ groupId: args["group-id"], output: args.output }) },
+})
+
+const tfTestersAddCmd = defineCommand({
+  meta: {
+    name: "add",
+    description: [
+      "Add a tester to a TestFlight group.",
+      "The tester will be invited via email and can install the app via TestFlight.",
+      "Provide email to create a new tester, or omit for a placeholder.",
+    ].join("\n"),
+  },
+  args: {
+    "group-id": { type: "string", description: "Beta Group ID. Use: asc testflight groups list", required: true },
+    email: { type: "string", description: "Tester email address" },
+    "first-name": { type: "string", description: "Tester first name" },
+    "last-name": { type: "string", description: "Tester last name" },
+  },
+  async run({ args }) {
+    await testflightTestersAdd({ groupId: args["group-id"], email: args.email, firstName: args["first-name"], lastName: args["last-name"] })
+  },
+})
+
+const tfTestersRemoveCmd = defineCommand({
+  meta: { name: "remove", description: "Remove a tester from a TestFlight group. The tester will lose access to the build." },
+  args: {
+    "group-id": { type: "string", description: "Beta Group ID. Use: asc testflight groups list", required: true },
+    "tester-id": { type: "string", description: "Tester ID (UUID). Use: asc testflight testers list --group-id <id>", required: true },
+  },
+  async run({ args }) {
+    await testflightTestersRemove({ groupId: args["group-id"], testerId: args["tester-id"] })
+  },
+})
+
+const tfTestersCmd = defineCommand({
+  meta: { name: "testers", description: "Add, remove, and list TestFlight testers within a group" },
+  subCommands: { list: tfTestersListCmd, add: tfTestersAddCmd, remove: tfTestersRemoveCmd },
+})
+
+const testflightCmd = defineCommand({
+  meta: {
+    name: "testflight",
+    description: [
+      "Manage TestFlight beta testing.",
+      "Workflow: asc testflight groups list → asc testflight testers add → distribute build to group.",
+    ].join("\n"),
+  },
+  subCommands: { groups: tfGroupsCmd, testers: tfTestersCmd },
+})
+
+// =============================================================================
+// METADATA
+// =============================================================================
+
+const metadataListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List all localizations for an App Store version. Shows locale, description, keywords, and promotional text.",
+  },
+  args: {
+    "version-id": { type: "string", description: "Version ID (UUID). Use: asc versions list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await metadataList({ versionId: args["version-id"], output: args.output }) },
+})
+
+const metadataUpdateCmd = defineCommand({
+  meta: {
+    name: "update",
+    description: [
+      "Update App Store metadata for a specific locale.",
+      "Provide one or more text fields to update.",
+      "Locale format: 'en-US', 'ja', 'fr-FR', 'de-DE', 'zh-Hans', etc.",
+      "",
+      "Example: asc metadata update --version-id <id> --locale en-US --whats-new 'Bug fixes'",
+    ].join("\n"),
+  },
+  args: {
+    "version-id": { type: "string", description: "Version ID (UUID). Use: asc versions list --app-id <id>", required: true },
+    locale: { type: "string", description: "Locale code, e.g. 'en-US', 'ja', 'fr-FR'", required: true },
+    "whats-new": { type: "string", description: "What's new in this version (shown in App Store update notes)" },
+    description: { type: "string", description: "Full app description text" },
+    keywords: { type: "string", description: "Search keywords, comma-separated (max 100 chars total)" },
+    "promotional-text": { type: "string", description: "Promotional text shown above the description (can be changed without a new submission)" },
+  },
+  async run({ args }) {
+    await metadataUpdate({
+      versionId: args["version-id"],
+      locale: args.locale,
+      whatsNew: args["whats-new"],
+      description: args.description,
+      keywords: args.keywords,
+      promotionalText: args["promotional-text"],
+    })
+  },
+})
+
+const metadataCmd = defineCommand({
+  meta: {
+    name: "metadata",
+    description: "Manage App Store listing text: descriptions, keywords, what's new, promotional text. Supports all locales.",
+  },
+  subCommands: { list: metadataListCmd, update: metadataUpdateCmd },
+})
+
+// =============================================================================
+// REVIEWS (Customer Reviews)
+// =============================================================================
+
+const reviewsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List customer reviews from the App Store. Returns rating, title, body, and territory.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await reviewsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const reviewsGetCmd = defineCommand({
+  meta: { name: "get", description: "Get a specific customer review by ID." },
+  args: {
+    "review-id": { type: "positional", description: "Review ID. Use: asc reviews list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await reviewsGet(args["review-id"], { output: args.output }) },
+})
+
+const reviewsRespondCmd = defineCommand({
+  meta: {
+    name: "respond",
+    description: [
+      "Post a developer response to a customer review.",
+      "Responses are public and visible in the App Store.",
+      "You can only respond once per review.",
+    ].join("\n"),
+  },
+  args: {
+    "review-id": { type: "string", description: "Review ID. Use: asc reviews list --app-id <id>", required: true },
+    message: { type: "string", description: "Response text (public, visible in App Store)", required: true },
+  },
+  async run({ args }) { await reviewsRespond({ reviewId: args["review-id"], message: args.message }) },
+})
+
+const reviewsCmd = defineCommand({
+  meta: {
+    name: "reviews",
+    description: "Read and respond to App Store customer reviews.",
+  },
+  subCommands: { list: reviewsListCmd, get: reviewsGetCmd, respond: reviewsRespondCmd },
+})
+
+// =============================================================================
+// PRICING
+// =============================================================================
+
+const pricingScheduleGetCmd = defineCommand({
+  meta: {
+    name: "get",
+    description: "Get the price schedule for an app including base territory and manual price overrides.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await pricingScheduleGet(args["app-id"], { output: args.output }) },
+})
+
+const pricingScheduleSetCmd = defineCommand({
+  meta: {
+    name: "set",
+    description: [
+      "Set the price for an app using a price point ID and base territory.",
+      "Use 'asc pricing points list --app-id <id>' to find available price points.",
+      "Base territory sets the reference currency (e.g. 'USA' for USD).",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    "base-territory": { type: "string", description: "Base territory code, e.g. 'USA', 'GBR', 'EUR'. Use: asc pricing territories list", required: true },
+    "price-point-id": { type: "string", description: "Price point ID. Use: asc pricing points list --app-id <id>", required: true },
+  },
+  async run({ args }) {
+    await pricingScheduleSet({ appId: args["app-id"], baseTerritory: args["base-territory"], pricePointId: args["price-point-id"] })
+  },
+})
+
+const pricingPointsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List available price points for an app.",
+      "Price points represent standard App Store price tiers.",
+      "Use --territory to filter for a specific storefront currency.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    territory: { type: "string", description: "Filter by territory code, e.g. 'USA', 'GBR'" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) {
+    await pricingPointsList({ appId: args["app-id"], territory: args.territory, output: args.output })
+  },
+})
+
+const territoriesListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List all App Store territories (storefronts) with their currency codes.",
+  },
+  args: { output: { type: "string", alias: "o", description: "Output format: table | json" } },
+  async run({ args }) { await territoriesList({ output: args.output }) },
+})
+
+const pricingCmd = defineCommand({
+  meta: {
+    name: "pricing",
+    description: [
+      "Manage app pricing: schedules, price points, and territory availability.",
+      "Workflow: asc pricing territories list → asc pricing points list --app-id <id> → asc pricing set",
+    ].join("\n"),
+  },
+  subCommands: {
+    get: pricingScheduleGetCmd,
+    set: pricingScheduleSetCmd,
+    points: defineCommand({ meta: { name: "points", description: "Manage price points" }, subCommands: { list: pricingPointsListCmd } }),
+    territories: defineCommand({ meta: { name: "territories", description: "List App Store territories" }, subCommands: { list: territoriesListCmd } }),
+  },
+})
+
+// =============================================================================
+// AVAILABILITY
+// =============================================================================
+
+const availabilityGetCmd = defineCommand({
+  meta: {
+    name: "get",
+    description: "Get the territory availability settings for an app, including which storefronts it is available in.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await availabilityGet(args["app-id"], { output: args.output }) },
+})
+
+const availabilitySetCmd = defineCommand({
+  meta: {
+    name: "set",
+    description: [
+      "Set which App Store territories the app is available in.",
+      "Provide a comma-separated list of territory codes.",
+      "Territory codes: USA, GBR, AUS, CAN, JPN, DEU, FRA, CHN, etc.",
+      "Use: asc pricing territories list to see all codes.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    territories: { type: "string", description: "Comma-separated territory codes, e.g. 'USA,GBR,AUS,CAN'", required: true },
+    "new-territories": { type: "boolean", description: "Allow distribution in newly added App Store territories automatically", default: true },
+  },
+  async run({ args }) {
+    const territories = args.territories.split(",").map(t => t.trim()).filter(Boolean)
+    await availabilityTerritoriesSet({ appId: args["app-id"], territories, availableInNewTerritories: args["new-territories"] })
+  },
+})
+
+const availabilityCmd = defineCommand({
+  meta: { name: "availability", description: "Manage which App Store territories an app is available in." },
+  subCommands: { get: availabilityGetCmd, set: availabilitySetCmd },
+})
+
+// =============================================================================
+// IAP (In-App Purchases)
+// =============================================================================
+
+const iapListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List in-app purchases for an app. Types: CONSUMABLE, NON_CONSUMABLE, NON_RENEWING_SUBSCRIPTION.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await iapList({ appId: args["app-id"], output: args.output }) },
+})
+
+const iapGetCmd = defineCommand({
+  meta: { name: "get", description: "Get details for a specific in-app purchase by its ID." },
+  args: {
+    "iap-id": { type: "positional", description: "IAP ID. Use: asc iap list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await iapGet(args["iap-id"], { output: args.output }) },
+})
+
+const iapCreateCmd = defineCommand({
+  meta: {
+    name: "create",
+    description: [
+      "Create a new in-app purchase product.",
+      "Types: CONSUMABLE | NON_CONSUMABLE | NON_RENEWING_SUBSCRIPTION",
+      "The product ID must be unique within your app (e.g. 'com.yourapp.coins100').",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    name: { type: "string", description: "Display name for the IAP (internal reference name)", required: true },
+    "product-id": { type: "string", description: "Unique product ID string, e.g. 'com.yourapp.premium'", required: true },
+    type: { type: "string", description: "IAP type: CONSUMABLE | NON_CONSUMABLE | NON_RENEWING_SUBSCRIPTION", required: true },
+  },
+  async run({ args }) {
+    await iapCreate({ appId: args["app-id"], name: args.name, productId: args["product-id"], type: args.type })
+  },
+})
+
+const iapDeleteCmd = defineCommand({
+  meta: { name: "delete", description: "Delete a draft in-app purchase. Cannot delete approved or submitted IAPs." },
+  args: { "iap-id": { type: "positional", description: "IAP ID. Use: asc iap list --app-id <id>", required: true } },
+  async run({ args }) { await iapDelete(args["iap-id"]) },
+})
+
+const iapCmd = defineCommand({
+  meta: {
+    name: "iap",
+    description: [
+      "Manage in-app purchases (consumables, non-consumables, non-renewing subscriptions).",
+      "For auto-renewable subscriptions, use: asc subscriptions",
+    ].join("\n"),
+  },
+  subCommands: { list: iapListCmd, get: iapGetCmd, create: iapCreateCmd, delete: iapDeleteCmd },
+})
+
+// =============================================================================
+// SUBSCRIPTIONS
+// =============================================================================
+
+const subGroupsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List subscription groups for an app. Groups organize related subscription tiers.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await subscriptionGroupsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const subGroupCreateCmd = defineCommand({
+  meta: { name: "create", description: "Create a new subscription group. Groups hold related subscription tiers." },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    "reference-name": { type: "string", description: "Internal reference name for this group (not shown to users)", required: true },
+  },
+  async run({ args }) {
+    await subscriptionGroupCreate({ appId: args["app-id"], referenceName: args["reference-name"] })
+  },
+})
+
+const subGroupsCmd = defineCommand({
+  meta: { name: "groups", description: "Manage subscription groups" },
+  subCommands: { list: subGroupsListCmd, create: subGroupCreateCmd },
+})
+
+const subscriptionsListCmd = defineCommand({
+  meta: { name: "list", description: "List auto-renewable subscriptions in a subscription group." },
+  args: {
+    "group-id": { type: "string", description: "Subscription Group ID. Use: asc subscriptions groups list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await subscriptionsList({ groupId: args["group-id"], output: args.output }) },
+})
+
+const subscriptionGetCmd = defineCommand({
+  meta: { name: "get", description: "Get details for a specific auto-renewable subscription." },
+  args: {
+    "sub-id": { type: "positional", description: "Subscription ID. Use: asc subscriptions list --group-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await subscriptionGet(args["sub-id"], { output: args.output }) },
+})
+
+const subscriptionCreateCmd = defineCommand({
+  meta: {
+    name: "create",
+    description: [
+      "Create a new auto-renewable subscription product.",
+      "Periods: ONE_WEEK | ONE_MONTH | TWO_MONTHS | THREE_MONTHS | SIX_MONTHS | ONE_YEAR",
+    ].join("\n"),
+  },
+  args: {
+    "group-id": { type: "string", description: "Subscription Group ID. Use: asc subscriptions groups list --app-id <id>", required: true },
+    name: { type: "string", description: "Internal reference name (not user-facing)", required: true },
+    "product-id": { type: "string", description: "Unique product ID, e.g. 'com.yourapp.premium.monthly'", required: true },
+    period: { type: "string", description: "Billing period: ONE_WEEK | ONE_MONTH | TWO_MONTHS | THREE_MONTHS | SIX_MONTHS | ONE_YEAR", required: true },
+  },
+  async run({ args }) {
+    await subscriptionCreate({ groupId: args["group-id"], name: args.name, productId: args["product-id"], period: args.period })
+  },
+})
+
+const subscriptionPricesListCmd = defineCommand({
+  meta: { name: "prices", description: "List price schedule for a subscription across territories." },
+  args: {
+    "sub-id": { type: "string", description: "Subscription ID. Use: asc subscriptions list --group-id <id>", required: true },
+    territory: { type: "string", description: "Filter by territory code, e.g. 'USA'" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) {
+    await subscriptionPricesList({ subId: args["sub-id"], territory: args.territory, output: args.output })
+  },
+})
+
+const subscriptionsCmd = defineCommand({
+  meta: {
+    name: "subscriptions",
+    description: [
+      "Manage auto-renewable subscription products.",
+      "Workflow: asc subscriptions groups list → asc subscriptions list → asc subscriptions create",
+    ].join("\n"),
+  },
+  subCommands: {
+    groups: subGroupsCmd,
+    list: subscriptionsListCmd,
+    get: subscriptionGetCmd,
+    create: subscriptionCreateCmd,
+    prices: subscriptionPricesListCmd,
+  },
+})
+
+// =============================================================================
+// APP-INFO
+// =============================================================================
+
+const appInfoGetCmd = defineCommand({
+  meta: {
+    name: "get",
+    description: "Get app info records showing age rating, content rating, and category for an app.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await appInfoGet(args["app-id"], { output: args.output }) },
+})
+
+const appInfoUpdateCmd = defineCommand({
+  meta: {
+    name: "update",
+    description: [
+      "Update the primary or secondary category for an app info record.",
+      "Use 'asc app-info categories' to see available category IDs.",
+      "Info ID comes from: asc app-info get --app-id <id>",
+    ].join("\n"),
+  },
+  args: {
+    "info-id": { type: "string", description: "App Info ID. Use: asc app-info get --app-id <id>", required: true },
+    "primary-category": { type: "string", description: "Primary category ID, e.g. 'GAMES', 'PRODUCTIVITY'. Use: asc app-info categories list" },
+    "secondary-category": { type: "string", description: "Secondary category ID (optional)" },
+  },
+  async run({ args }) {
+    await appInfoUpdate({ infoId: args["info-id"], primaryCategoryId: args["primary-category"], secondaryCategoryId: args["secondary-category"] })
+  },
+})
+
+const appCategoriesListCmd = defineCommand({
+  meta: { name: "list", description: "List all App Store categories. Use these IDs with 'asc app-info update'." },
+  args: {
+    platform: { type: "string", description: "Filter by platform: IOS | MAC_OS | TV_OS" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await appCategoriesList({ platform: args.platform, output: args.output }) },
+})
+
+const appInfoCmd = defineCommand({
+  meta: { name: "app-info", description: "Manage app info: categories, age ratings, content declarations." },
+  subCommands: {
+    get: appInfoGetCmd,
+    update: appInfoUpdateCmd,
+    categories: defineCommand({ meta: { name: "categories", description: "App category management" }, subCommands: { list: appCategoriesListCmd } }),
+  },
+})
+
+// =============================================================================
+// SCREENSHOTS
+// =============================================================================
+
+const screenshotSetsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List screenshot sets for a version localization.",
+      "Each set holds screenshots for a specific device display type.",
+      "Localization IDs come from: asc metadata list --version-id <id>",
+    ].join("\n"),
+  },
+  args: {
+    "localization-id": { type: "string", description: "Version Localization ID. Use: asc metadata list --version-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await screenshotSetsList({ versionLocalizationId: args["localization-id"], output: args.output }) },
+})
+
+const screenshotsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List screenshots in a screenshot set. Shows file names, sizes, and upload state.",
+  },
+  args: {
+    "set-id": { type: "string", description: "Screenshot Set ID. Use: asc screenshots sets list --localization-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await screenshotsList({ setId: args["set-id"], output: args.output }) },
+})
+
+const screenshotUploadCmd = defineCommand({
+  meta: {
+    name: "upload",
+    description: [
+      "Upload a screenshot image file to a screenshot set.",
+      "Supported formats: PNG, JPEG.",
+      "Screenshot sets correspond to device types (e.g. 6.5-inch iPhone display).",
+    ].join("\n"),
+  },
+  args: {
+    "set-id": { type: "string", description: "Screenshot Set ID. Use: asc screenshots sets list --localization-id <id>", required: true },
+    file: { type: "string", description: "Path to the screenshot image file (PNG or JPEG)", required: true },
+  },
+  async run({ args }) { await screenshotCreate({ setId: args["set-id"], filePath: args.file }) },
+})
+
+const screenshotDeleteCmd = defineCommand({
+  meta: { name: "delete", description: "Delete a screenshot from a screenshot set." },
+  args: { "screenshot-id": { type: "positional", description: "Screenshot ID. Use: asc screenshots list --set-id <id>", required: true } },
+  async run({ args }) { await screenshotDelete(args["screenshot-id"]) },
+})
+
+const previewSetsListCmd = defineCommand({
+  meta: { name: "list", description: "List app preview sets for a version localization." },
+  args: {
+    "localization-id": { type: "string", description: "Version Localization ID. Use: asc metadata list --version-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await previewSetsList({ versionLocalizationId: args["localization-id"], output: args.output }) },
+})
+
+const screenshotsCmd = defineCommand({
+  meta: {
+    name: "screenshots",
+    description: "Manage App Store screenshots and app previews. Workflow: list sets → list screenshots → upload/delete.",
+  },
+  subCommands: {
+    sets: defineCommand({
+      meta: { name: "sets", description: "Screenshot set management" },
+      subCommands: { list: screenshotSetsListCmd },
+    }),
+    list: screenshotsListCmd,
+    upload: screenshotUploadCmd,
+    delete: screenshotDeleteCmd,
+    previews: defineCommand({
+      meta: { name: "previews", description: "App preview sets" },
+      subCommands: { list: previewSetsListCmd },
+    }),
+  },
+})
+
+// =============================================================================
+// SIGNING
+// =============================================================================
+
+const certsListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List certificates in your account.",
+      "Types: IOS_DEVELOPMENT | IOS_DISTRIBUTION | MAC_APP_DISTRIBUTION | MAC_INSTALLER_DISTRIBUTION",
+      "       DEVELOPER_ID_APPLICATION | DEVELOPER_ID_INSTALLER",
+    ].join("\n"),
+  },
+  args: {
+    type: { type: "string", description: "Filter by certificate type, e.g. 'IOS_DISTRIBUTION'" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await certificatesList({ type: args.type, output: args.output }) },
+})
+
+const certsGetCmd = defineCommand({
+  meta: { name: "get", description: "Get certificate details by ID." },
+  args: {
+    "cert-id": { type: "positional", description: "Certificate ID. Use: asc signing certs list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await certificateGet(args["cert-id"], { output: args.output }) },
+})
+
+const certsRevokeCmd = defineCommand({
+  meta: { name: "revoke", description: "Revoke a certificate. This will invalidate any provisioning profiles using this certificate." },
+  args: { "cert-id": { type: "positional", description: "Certificate ID. Use: asc signing certs list", required: true } },
+  async run({ args }) { await certificateRevoke(args["cert-id"]) },
+})
+
+const certsCmd = defineCommand({
+  meta: { name: "certs", description: "Manage signing certificates" },
+  subCommands: { list: certsListCmd, get: certsGetCmd, revoke: certsRevokeCmd },
+})
+
+const devicesListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: "List registered test devices. Only enabled devices can be included in development/ad-hoc provisioning profiles.",
+  },
+  args: {
+    platform: { type: "string", description: "Filter by platform: IOS | MAC_OS | TV_OS" },
+    status: { type: "string", description: "Filter by status: ENABLED | DISABLED" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await devicesList({ platform: args.platform, status: args.status, output: args.output }) },
+})
+
+const devicesRegisterCmd = defineCommand({
+  meta: {
+    name: "register",
+    description: [
+      "Register a new device for development/testing.",
+      "The UDID can be found in Xcode → Devices & Simulators, or in System Information.",
+      "Platforms: IOS | MAC_OS | TV_OS | WATCH_OS | VISION_OS",
+    ].join("\n"),
+  },
+  args: {
+    name: { type: "string", description: "Display name for the device", required: true },
+    udid: { type: "string", description: "Device UDID (40 hex characters for iOS, 12+2+12 for Mac)", required: true },
+    platform: { type: "string", description: "Platform: IOS | MAC_OS | TV_OS | WATCH_OS | VISION_OS", required: true },
+  },
+  async run({ args }) { await deviceRegister({ name: args.name, udid: args.udid, platform: args.platform }) },
+})
+
+const devicesCmd = defineCommand({
+  meta: { name: "devices", description: "Register and list test devices for development profiles" },
+  subCommands: { list: devicesListCmd, register: devicesRegisterCmd },
+})
+
+const bundleIdsListCmd = defineCommand({
+  meta: { name: "list", description: "List registered bundle IDs (App IDs) in your account." },
+  args: {
+    platform: { type: "string", description: "Filter by platform: IOS | MAC_OS | UNIVERSAL" },
+    identifier: { type: "string", description: "Filter by bundle identifier string, e.g. 'com.yourapp'" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await bundleIdsList({ platform: args.platform, identifier: args.identifier, output: args.output }) },
+})
+
+const bundleIdsRegisterCmd = defineCommand({
+  meta: { name: "register", description: "Register a new bundle ID (App ID). Required before creating provisioning profiles." },
+  args: {
+    name: { type: "string", description: "Display name for this bundle ID", required: true },
+    identifier: { type: "string", description: "Bundle identifier string, e.g. 'com.yourcompany.yourapp'", required: true },
+    platform: { type: "string", description: "Platform: IOS | MAC_OS | UNIVERSAL", required: true },
+  },
+  async run({ args }) { await bundleIdRegister({ name: args.name, identifier: args.identifier, platform: args.platform }) },
+})
+
+const bundleIdsCmd = defineCommand({
+  meta: { name: "bundle-ids", description: "Register and list bundle IDs (App IDs)" },
+  subCommands: { list: bundleIdsListCmd, register: bundleIdsRegisterCmd },
+})
+
+const profilesListCmd = defineCommand({
+  meta: {
+    name: "list",
+    description: [
+      "List provisioning profiles in your account.",
+      "Types: IOS_APP_DEVELOPMENT | IOS_APP_STORE | IOS_APP_ADHOC | IOS_APP_INHOUSE",
+      "       MAC_APP_DEVELOPMENT | MAC_APP_STORE | MAC_APP_DIRECT | TVOS_APP_DEVELOPMENT",
+    ].join("\n"),
+  },
+  args: {
+    type: { type: "string", description: "Filter by profile type, e.g. 'IOS_APP_STORE'" },
+    name: { type: "string", description: "Filter by profile name (partial match)" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await profilesList({ type: args.type, name: args.name, output: args.output }) },
+})
+
+const profilesDeleteCmd = defineCommand({
+  meta: { name: "delete", description: "Delete a provisioning profile." },
+  args: { "profile-id": { type: "positional", description: "Profile ID. Use: asc signing profiles list", required: true } },
+  async run({ args }) { await profileDelete(args["profile-id"]) },
+})
+
+const profilesCmd = defineCommand({
+  meta: { name: "profiles", description: "List and delete provisioning profiles" },
+  subCommands: { list: profilesListCmd, delete: profilesDeleteCmd },
+})
+
+const signingCmd = defineCommand({
+  meta: {
+    name: "signing",
+    description: [
+      "Manage code signing resources: certificates, devices, bundle IDs, and provisioning profiles.",
+      "Workflow: bundle-ids register → devices register → certs list → profiles list",
+    ].join("\n"),
+  },
+  subCommands: { certs: certsCmd, devices: devicesCmd, "bundle-ids": bundleIdsCmd, profiles: profilesCmd },
+})
+
+// =============================================================================
+// REPORTS
+// =============================================================================
+
+const salesReportCmd = defineCommand({
+  meta: {
+    name: "sales",
+    description: [
+      "Download a sales and trends report in TSV format (gzip decompressed).",
+      "By default outputs raw TSV. Use --output json to get structured JSON.",
+      "",
+      "Frequencies: DAILY | WEEKLY | MONTHLY | YEARLY",
+      "Report types: SALES | SUBSCRIPTION | SUBSCRIPTION_EVENT | SUBSCRIBER | PRE_ORDER",
+      "Report date format: YYYY-MM-DD for DAILY, YYYY-MM for MONTHLY, YYYY for YEARLY",
+      "",
+      "Example: asc reports sales --vendor-number 12345678 --frequency MONTHLY --date 2024-01",
+    ].join("\n"),
+  },
+  args: {
+    "vendor-number": { type: "string", description: "Vendor number from App Store Connect → Payments & Financial Reports", required: true },
+    frequency: { type: "string", description: "Report frequency: DAILY | WEEKLY | MONTHLY | YEARLY", required: true },
+    date: { type: "string", description: "Report date. DAILY: YYYY-MM-DD, MONTHLY: YYYY-MM, YEARLY: YYYY", required: true },
+    "report-type": { type: "string", description: "Report type: SALES (default) | SUBSCRIPTION | SUBSCRIPTION_EVENT | SUBSCRIBER | PRE_ORDER" },
+    "report-subtype": { type: "string", description: "Report subtype: SUMMARY (default) | DETAILED" },
+    output: { type: "string", alias: "o", description: "Output format: tsv (default) | json" },
+  },
+  async run({ args }) {
+    await salesReportDownload({
+      vendorNumber: args["vendor-number"],
+      frequency: args.frequency,
+      reportDate: args.date,
+      reportType: args["report-type"],
+      reportSubType: args["report-subtype"],
+      output: args.output,
+    })
+  },
+})
+
+const financeReportCmd = defineCommand({
+  meta: {
+    name: "finance",
+    description: [
+      "Download a financial report for a given region and month.",
+      "Region codes: US, EU, WW, JP, etc.",
+      "Report date format: YYYY-MM",
+      "",
+      "Example: asc reports finance --vendor-number 12345678 --region US --date 2024-01",
+    ].join("\n"),
+  },
+  args: {
+    "vendor-number": { type: "string", description: "Vendor number from App Store Connect → Payments & Financial Reports", required: true },
+    region: { type: "string", description: "Region code: US | EU | WW | JP | CN | AU | CA | GB | etc.", required: true },
+    date: { type: "string", description: "Report month in YYYY-MM format", required: true },
+    output: { type: "string", alias: "o", description: "Output format: tsv (default) | json" },
+  },
+  async run({ args }) {
+    await financeReportDownload({ vendorNumber: args["vendor-number"], regionCode: args.region, reportDate: args.date, output: args.output })
+  },
+})
+
+const analyticsListCmd = defineCommand({
+  meta: { name: "list", description: "List analytics report requests for an app." },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await analyticsReportsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const analyticsRequestCmd = defineCommand({
+  meta: {
+    name: "request",
+    description: [
+      "Request an analytics report for an app.",
+      "Access types: ONE_TIME_SNAPSHOT | ONGOING",
+      "Reports are generated asynchronously. Check status with: asc reports analytics list",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    category: { type: "string", description: "Access type: ONE_TIME_SNAPSHOT | ONGOING", default: "ONE_TIME_SNAPSHOT" },
+  },
+  async run({ args }) { await analyticsReportRequest({ appId: args["app-id"], category: args.category }) },
+})
+
+const reportsCmd = defineCommand({
+  meta: {
+    name: "reports",
+    description: [
+      "Download sales, finance, and analytics reports.",
+      "Sales/finance reports output TSV (piped) or JSON (--output json).",
+      "Vendor number is found at App Store Connect → Payments & Financial Reports.",
+    ].join("\n"),
+  },
+  subCommands: {
+    sales: salesReportCmd,
+    finance: financeReportCmd,
+    analytics: defineCommand({
+      meta: { name: "analytics", description: "Analytics report requests" },
+      subCommands: { list: analyticsListCmd, request: analyticsRequestCmd },
+    }),
+  },
+})
+
+// =============================================================================
+// XCODE CLOUD
+// =============================================================================
+
+const xcProductsListCmd = defineCommand({
+  meta: { name: "list", description: "List Xcode Cloud products. Each product is linked to one app." },
+  args: {
+    "app-id": { type: "string", description: "Filter by App ID. Use: asc apps list" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await xcodeCloudProductsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const xcWorkflowsListCmd = defineCommand({
+  meta: { name: "list", description: "List Xcode Cloud workflows for a product." },
+  args: {
+    "product-id": { type: "string", description: "Xcode Cloud Product ID. Use: asc xcode-cloud products list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await workflowsList({ productId: args["product-id"], output: args.output }) },
+})
+
+const xcWorkflowGetCmd = defineCommand({
+  meta: { name: "get", description: "Get details for a specific Xcode Cloud workflow." },
+  args: {
+    "workflow-id": { type: "positional", description: "Workflow ID. Use: asc xcode-cloud workflows list --product-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await workflowGet(args["workflow-id"], { output: args.output }) },
+})
+
+const xcBuildsListCmd = defineCommand({
+  meta: { name: "list", description: "List Xcode Cloud build runs. Filter by workflow or product." },
+  args: {
+    "workflow-id": { type: "string", description: "Filter by Workflow ID. Use: asc xcode-cloud workflows list --product-id <id>" },
+    "product-id": { type: "string", description: "Filter by Xcode Cloud Product ID" },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await xcodeCloudBuildsList({ workflowId: args["workflow-id"], productId: args["product-id"], output: args.output }) },
+})
+
+const xcBuildRunCmd = defineCommand({
+  meta: {
+    name: "run",
+    description: [
+      "Trigger a new Xcode Cloud build run for a workflow.",
+      "Optionally specify a branch to build. Defaults to the workflow's configured start condition.",
+    ].join("\n"),
+  },
+  args: {
+    "workflow-id": { type: "string", description: "Workflow ID. Use: asc xcode-cloud workflows list --product-id <id>", required: true },
+    branch: { type: "string", description: "Git branch to build (optional, uses workflow default if omitted)" },
+  },
+  async run({ args }) { await xcodeCloudBuildRun({ workflowId: args["workflow-id"], branch: args.branch }) },
+})
+
+const xcArtifactsListCmd = defineCommand({
+  meta: { name: "list", description: "List artifacts (logs, archives, test results) from an Xcode Cloud build run." },
+  args: {
+    "build-id": { type: "string", description: "Build Run ID. Use: asc xcode-cloud builds list --workflow-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await xcodeCloudArtifactsList({ buildRunId: args["build-id"], output: args.output }) },
+})
+
+const xcTestResultsListCmd = defineCommand({
+  meta: { name: "list", description: "List test results from an Xcode Cloud build run." },
+  args: {
+    "build-id": { type: "string", description: "Build Run ID. Use: asc xcode-cloud builds list --workflow-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await xcodeCloudTestResultsList({ buildRunId: args["build-id"], output: args.output }) },
+})
+
+const xcodeCloudCmd = defineCommand({
+  meta: {
+    name: "xcode-cloud",
+    description: [
+      "Manage Xcode Cloud CI/CD workflows and build runs.",
+      "Workflow: products list → workflows list → builds run → artifacts list",
+    ].join("\n"),
+  },
+  subCommands: {
+    products: defineCommand({ meta: { name: "products", description: "Xcode Cloud products" }, subCommands: { list: xcProductsListCmd } }),
+    workflows: defineCommand({ meta: { name: "workflows", description: "Xcode Cloud workflows" }, subCommands: { list: xcWorkflowsListCmd, get: xcWorkflowGetCmd } }),
+    builds: defineCommand({ meta: { name: "builds", description: "Xcode Cloud build runs" }, subCommands: { list: xcBuildsListCmd, run: xcBuildRunCmd } }),
+    artifacts: defineCommand({ meta: { name: "artifacts", description: "Build artifacts" }, subCommands: { list: xcArtifactsListCmd } }),
+    "test-results": defineCommand({ meta: { name: "test-results", description: "Test results" }, subCommands: { list: xcTestResultsListCmd } }),
+  },
+})
+
+// =============================================================================
+// GAME CENTER
+// =============================================================================
+
+const gcAchievementsListCmd = defineCommand({
+  meta: { name: "list", description: "List Game Center achievements for an app." },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await achievementsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const gcAchievementsGetCmd = defineCommand({
+  meta: { name: "get", description: "Get details for a specific Game Center achievement." },
+  args: {
+    "achievement-id": { type: "positional", description: "Achievement ID. Use: asc game-center achievements list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await achievementGet(args["achievement-id"], { output: args.output }) },
+})
+
+const gcLeaderboardsListCmd = defineCommand({
+  meta: { name: "list", description: "List Game Center leaderboards for an app." },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await leaderboardsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const gcLeaderboardSetsListCmd = defineCommand({
+  meta: { name: "list", description: "List Game Center leaderboard sets for an app." },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await leaderboardSetsList({ appId: args["app-id"], output: args.output }) },
+})
+
+const gameCenterCmd = defineCommand({
+  meta: {
+    name: "game-center",
+    description: "Manage Game Center features: achievements, leaderboards, and leaderboard sets.",
+  },
+  subCommands: {
+    achievements: defineCommand({
+      meta: { name: "achievements", description: "Game Center achievements" },
+      subCommands: { list: gcAchievementsListCmd, get: gcAchievementsGetCmd },
+    }),
+    leaderboards: defineCommand({
+      meta: { name: "leaderboards", description: "Game Center leaderboards" },
+      subCommands: { list: gcLeaderboardsListCmd },
+    }),
+    "leaderboard-sets": defineCommand({
+      meta: { name: "leaderboard-sets", description: "Game Center leaderboard sets" },
+      subCommands: { list: gcLeaderboardSetsListCmd },
+    }),
+  },
+})
+
+// =============================================================================
+// BETA REVIEW
+// =============================================================================
+
+const betaReviewSubmitCmd = defineCommand({
+  meta: {
+    name: "submit",
+    description: [
+      "Submit a build for TestFlight external beta review.",
+      "Required before distributing to external testers (outside your org).",
+      "Internal testers do not require beta review.",
+      "Build ID comes from: asc builds list --app-id <id>",
+    ].join("\n"),
+  },
+  args: { "build-id": { type: "positional", description: "Build ID (UUID). Use: asc builds list --app-id <id>", required: true } },
+  async run({ args }) { await betaReviewSubmissionCreate(args["build-id"]) },
+})
+
+const betaReviewStatusCmd = defineCommand({
+  meta: { name: "status", description: "Check the beta review status for a build." },
+  args: {
+    "build-id": { type: "string", description: "Build ID (UUID). Use: asc builds list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await betaReviewSubmissionGet(args["build-id"], { output: args.output }) },
+})
+
+const betaReviewDetailGetCmd = defineCommand({
+  meta: {
+    name: "get",
+    description: "Get the beta app review details including contact information and demo account credentials.",
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await betaReviewDetailGet(args["app-id"], { output: args.output }) },
+})
+
+const betaReviewDetailUpdateCmd = defineCommand({
+  meta: {
+    name: "update",
+    description: [
+      "Update the beta app review details including reviewer contact and demo account.",
+      "This information is provided to the Apple review team when reviewing your TestFlight build.",
+    ].join("\n"),
+  },
+  args: {
+    "app-id": { type: "string", description: "App ID. Use: asc apps list", required: true },
+    "contact-first-name": { type: "string", description: "Review contact first name" },
+    "contact-last-name": { type: "string", description: "Review contact last name" },
+    "contact-email": { type: "string", description: "Review contact email address" },
+    "contact-phone": { type: "string", description: "Review contact phone number" },
+    "demo-account-name": { type: "string", description: "Demo account username (if demo account required)" },
+    "demo-account-password": { type: "string", description: "Demo account password" },
+    "demo-account-required": { type: "boolean", description: "Whether a demo account is required for review" },
+    notes: { type: "string", description: "Additional notes for the review team" },
+  },
+  async run({ args }) {
+    await betaReviewDetailUpdate({
+      appId: args["app-id"],
+      contactFirstName: args["contact-first-name"],
+      contactLastName: args["contact-last-name"],
+      contactEmail: args["contact-email"],
+      contactPhone: args["contact-phone"],
+      demoAccountName: args["demo-account-name"],
+      demoAccountPassword: args["demo-account-password"],
+      demoAccountRequired: args["demo-account-required"],
+      notes: args.notes,
+    })
+  },
+})
+
+const betaBuildNotifyCmd = defineCommand({
+  meta: {
+    name: "notify",
+    description: "Enable or disable automatic tester notifications when a build is approved for testing.",
+  },
+  args: {
+    "build-id": { type: "string", description: "Build ID (UUID). Use: asc builds list --app-id <id>", required: true },
+    enabled: { type: "boolean", description: "Set to true to auto-notify testers, false to suppress notifications", default: true },
+  },
+  async run({ args }) { await buildBetaDetailUpdate({ buildId: args["build-id"], autoNotifyEnabled: args.enabled }) },
+})
+
+const betaBuildLocalesListCmd = defineCommand({
+  meta: { name: "list", description: "List TestFlight 'What to Test' localizations for a build." },
+  args: {
+    "build-id": { type: "string", description: "Build ID (UUID). Use: asc builds list --app-id <id>", required: true },
+    output: { type: "string", alias: "o", description: "Output format: table | json" },
+  },
+  async run({ args }) { await betaBuildLocalizationsList({ buildId: args["build-id"], output: args.output }) },
+})
+
+const betaReviewCmd = defineCommand({
+  meta: {
+    name: "beta-review",
+    description: [
+      "Manage TestFlight external beta review submissions and review details.",
+      "External testers require beta app review before accessing builds.",
+      "Internal testers (App Store Connect users) do not require review.",
+    ].join("\n"),
+  },
+  subCommands: {
+    submit: betaReviewSubmitCmd,
+    status: betaReviewStatusCmd,
+    "detail-get": betaReviewDetailGetCmd,
+    "detail-update": betaReviewDetailUpdateCmd,
+    notify: betaBuildNotifyCmd,
+    localizations: defineCommand({ meta: { name: "localizations", description: "Build beta localizations" }, subCommands: { list: betaBuildLocalesListCmd } }),
+  },
+})
+
+// =============================================================================
+// ROOT
+// =============================================================================
+
+const main = defineCommand({
+  meta: {
+    name: "asc",
+    version: pkg.version,
+    description: [
+      "App Store Connect CLI — manage apps, builds, TestFlight, metadata and more.",
+      "",
+      "QUICK START:",
+      "  1. asc auth login     → add your API key credentials",
+      "  2. asc apps list      → find your App ID",
+      "  3. asc builds list    → see recent builds",
+      "",
+      "All commands output tables in TTY mode and JSON when piped.",
+      "Use --output json to force JSON output for programmatic use.",
+      "",
+      "GLOBAL FLAGS:",
+      "  --profile <name>     Use a specific profile for this command (e.g. --profile personal)",
+      "                       Equivalent to setting ASC_PROFILE=<name>",
+      "                       See all profiles: asc auth list",
+      "",
+      "  ASC_KEY_ID           App Store Connect API Key ID",
+      "  ASC_ISSUER_ID        Issuer ID (UUID)",
+      "  ASC_PRIVATE_KEY_PATH Path to .p8 private key file",
+      "  ASC_BYPASS_KEYCHAIN  Set to '1' to skip Keychain storage",
+      "",
+      "REGENERATE API CLIENT (when Apple updates their API):",
+      "  bun run generate",
+      "",
+      "AI AGENTS:",
+      "  asc --help --json    Full command tree as structured JSON (pipe to jq or save to file)",
+    ].join("\n"),
+  },
+  subCommands: {
+    auth: authCmd,
+    apps: appsCmd,
+    builds: buildsCmd,
+    versions: versionsCmd,
+    testflight: testflightCmd,
+    metadata: metadataCmd,
+    reviews: reviewsCmd,
+    pricing: pricingCmd,
+    availability: availabilityCmd,
+    iap: iapCmd,
+    subscriptions: subscriptionsCmd,
+    "app-info": appInfoCmd,
+    screenshots: screenshotsCmd,
+    signing: signingCmd,
+    reports: reportsCmd,
+    "xcode-cloud": xcodeCloudCmd,
+    "game-center": gameCenterCmd,
+    "beta-review": betaReviewCmd,
+  },
+})
+
+// ---- Global --help --json flag ----
+// When both --help and --json are present, output the full command tree as JSON
+// and exit. This is more discoverable than a dedicated subcommand since agents
+// and humans both start with --help.
+if (process.argv.includes("--help") && process.argv.includes("--json")) {
+  console.log(JSON.stringify(buildHelpDocument(), null, 2))
+  process.exit(0)
+}
+
+// ---- Global --profile flag ----
+// Parse --profile <name> from raw args early so getActiveProfile() picks it up
+// via process.env["ASC_PROFILE"] regardless of which subcommand runs.
+// This mirrors how `aws --profile <name>` works.
+const profileFlagIdx = process.argv.indexOf("--profile")
+if (profileFlagIdx !== -1) {
+  const profileFlagValue = process.argv[profileFlagIdx + 1]
+  if (profileFlagValue && !profileFlagValue.startsWith("-")) {
+    process.env["ASC_PROFILE"] = profileFlagValue
+    // Remove from argv so citty doesn't see an unknown flag
+    process.argv.splice(profileFlagIdx, 2)
+  }
+}
+
+// ---- Intercept citty's error output ----
+// Citty uses consola to print errors, which includes full stack traces.
+// Override consola.error to route through our clean printError formatter.
+// Citty calls it twice for non-CLI errors: once with the Error object,
+// once with error.message as a string — suppress the duplicate string call.
+{
+  const consola = (await import("consola")).consola
+  let _lastErrorMessage: string | null = null
+  const _origError = consola.error.bind(consola)
+  ;(consola as unknown as Record<string, unknown>).error = (err: unknown, ..._rest: unknown[]) => {
+    if (err instanceof Error) {
+      printError(err)
+      _lastErrorMessage = err.message
+    } else if (typeof err === "string" && err === _lastErrorMessage) {
+      _lastErrorMessage = null // suppress duplicate
+    } else {
+      _origError(err)
+    }
+  }
+}
+
+runMain(main).catch((err) => {
+  printError(err)
+  process.exit(1)
+})