{
  "slug": "asc-flag-must-be-passed-after-subcommand",
  "url": "https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand",
  "markdown_url": "https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand.md",
  "title": "ASC CLI: \"--<flag> must be passed after the subcommand name\"",
  "description": "asc 5.11.0+ rejects flags placed between a command group and its subcommand (asc reviews --stars 1 list). Move the flag after the subcommand.",
  "tool": {
    "id": "asc",
    "name": "ASC CLI",
    "long_name": "App Store Connect CLI (asc)",
    "url": "https://insidetheloop.dev/tools/asc",
    "latest_version": "5.13.0"
  },
  "error": "Error: --stars must be passed after the subcommand name (asc reviews list [flags])",
  "variants": [
    "Error: unknown flag `--app` for `asc builds`"
  ],
  "output": "Error: --stars must be passed after the subcommand name (asc reviews list [flags])",
  "exit_code": 2,
  "command": "asc reviews --stars 1 list --app 123",
  "versions": {
    "affected": "5.11.0 and later",
    "first_bad": "5.11.0",
    "last_good": "5.10.0",
    "fixed_in": null,
    "tested": [
      "5.10.0",
      "5.11.0",
      "5.13.0"
    ]
  },
  "cause": "Since ASC CLI 5.11.0 (released 2026-10-05), a flag written between a command group and its subcommand (`asc reviews --stars 1 list`) is an error, because older versions parsed it into the group and then silently dropped it.",
  "fix": {
    "summary": "Put every flag after the leaf subcommand: `asc reviews list --stars 1 --app 123`, `asc builds list --app 123`.",
    "commands": [
      "# wrong: asc reviews --stars 1 list --app 123",
      "asc reviews list --stars 1 --app 123",
      "",
      "# wrong: asc builds --app 123 list",
      "asc builds list --app 123"
    ],
    "note": "The flag name and command in the message change with your command line. Some groups, such as `asc builds`, print an `unknown flag` error for the same mistake instead (shown below); that form already failed in 5.10.0, and 5.11.0 added a \"Did you mean a subcommand?\" line listing the subcommands that accept the flag. On 5.10.0 the `reviews` command ran without the `--stars` filter."
  },
  "reproduction": {
    "ran_at": "2026-10-07T14:10:57Z",
    "environment": "A fresh Debian 13 VM from `bin/sandbox-run` (Node.js 24, root, online, no credentials for any service), destroyed after the run.",
    "steps": [
      {
        "label": "Before: the flag is accepted and dropped; the command continues to authentication",
        "version": "5.10.0",
        "command": "asc reviews --stars 1 list --app 123",
        "output": "Error: reviews: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init')\nHint: Run `asc auth login` or `asc auth init` (or set ASC_KEY_ID/ASC_ISSUER_ID/ASC_PRIVATE_KEY_PATH). Try `asc auth doctor` if you're unsure what's misconfigured.",
        "exit": 3
      },
      {
        "label": "After: rejected",
        "version": "5.11.0",
        "command": "asc reviews --stars 1 list --app 123",
        "output": "Error: --stars must be passed after the subcommand name (asc reviews list [flags])",
        "exit": 2
      },
      {
        "label": "Same in the latest release",
        "version": "5.13.0",
        "command": "asc reviews --stars 1 list --app 123",
        "output": "Error: --stars must be passed after the subcommand name (asc reviews list [flags])",
        "exit": 2
      },
      {
        "label": "The `unknown flag` form on the builds group",
        "version": "5.13.0",
        "command": "asc builds --app 123 list",
        "output": "Error: unknown flag `--app` for `asc builds`\nDid you mean a subcommand? These accept `--app`: list, count, next-build-number, wait, info, expire, expire-all, upload, update, add-groups, remove-groups, dsyms\nFor help:\n  asc builds --help",
        "exit": 2
      },
      {
        "label": "Fix verified: flags after the subcommand reach authentication",
        "version": "5.13.0",
        "command": "asc reviews list --stars 1 --app 123",
        "output": "Error: reviews: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init')\nHint: Run `asc auth status` to see configured credentials. To add an API key, create one at https://appstoreconnect.apple.com/access/integrations/api and run `asc auth login --name MyKey --key-id KEY_ID --issuer-id ISSUER_ID --private-key /path/to/AuthKey_KEY_ID.p8` (or set ASC_KEY_ID/ASC_ISSUER_ID/ASC_PRIVATE_KEY_PATH).",
        "exit": 3
      }
    ]
  },
  "why": {
    "text": "Pull request #2889 (merged 2026-10-05, shipped in 5.11.0) explains that the CLI framework parsed `--flag` into the group's flag set \"and then silently dropped\" it, so `asc reviews --stars 1 list --app 123` \"sent no rating filter\"; the fix rejects such flags instead of ignoring them.",
    "url": "https://github.com/rorkai/App-Store-Connect-CLI/pull/2889",
    "source": "rorkai/App-Store-Connect-CLI PR #2889"
  },
  "tool_page": "https://insidetheloop.dev/tools/asc#gotcha-flag-placed-on-the-command-group-instead-of-the-subcommand",
  "related": [
    {
      "slug": "asc-png-alpha-channel-rejected",
      "error": "image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha",
      "url": "https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected"
    }
  ],
  "sources": [
    {
      "title": "fix(cli): reject group flags placed before a subcommand (PR #2889)",
      "url": "https://github.com/rorkai/App-Store-Connect-CLI/pull/2889",
      "read": "2026-10-07"
    },
    {
      "title": "ASC CLI 5.11.0 release notes",
      "url": "https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.11.0",
      "read": "2026-10-07"
    }
  ],
  "date_published": "2026-10-07T14:15:32Z",
  "date_modified": "2026-10-07T14:15:32Z",
  "verified": {
    "date": "2026-10-07",
    "versions": [
      "5.10.0",
      "5.11.0",
      "5.13.0"
    ]
  }
}