fix(cli): allow parent options after subcommand arguments

Enables parent/global options to appear anywhere in the command line,
including after subcommand names and their arguments. This follows the
common CLI pattern used by git, npm, docker, and most modern CLI tools.

Before:
  cli --global-opt subcommand arg     # works
  cli subcommand arg --global-opt     # fails: "unknown option"

After:
  cli --global-opt subcommand arg     # works
  cli subcommand arg --global-opt     # works

This is useful for the "centralized flags" pattern where global options
like --verbose, --config, or --model are defined on the parent command
and inherited by all subcommands. Users can now place these options
at the end of the command for better ergonomics.

Implementation:
- Extract parent option names before splitting args at subcommand boundary
- Scan args after subcommand for known parent options
- Pass extracted parent options to parent command parsing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: cevr

packages/cli/src/internal/commandDescriptor.ts

@@ -669,10 +669,27 @@ const parseInternal = (
     case "Subcommands": {
       const names = getNamesInternal(self)
       const subcommands = getSubcommandsInternal(self)
-      const [parentArgs, childArgs] = Arr.span(
+      const subcommandNames = Arr.map(subcommands, ([name]) => name)
+
+      // Get parent option names so we can extract them from anywhere in args
+      const parentOptionNames = getParentOptionNames(self.parent)
+
+      // Extract parent options that appear after the subcommand
+      const { parentArgs: extractedParentArgs, remainingArgs } = extractParentOptionsFromArgs(
         args,
+        parentOptionNames,
+        subcommandNames
+      )
+
+      // Split remaining args at subcommand boundary (original logic)
+      const [preSubcommandArgs, childArgs] = Arr.span(
+        remainingArgs,
         (arg) => !Arr.some(subcommands, ([name]) => name === arg)
       )
+
+      // Combine args before subcommand with extracted parent options
+      const parentArgs = Arr.appendAll(preSubcommandArgs, extractedParentArgs)
+
       const parseChildrenWith = (argsForChildren: ReadonlyArray<string>) =>
         Effect.suspend(() => {
           const iterator = self.children[Symbol.iterator]()
@@ -828,6 +845,111 @@ const splitForcedArgs = (
   return [remainingArgs, Arr.drop(forcedArgs, 1)]
 }
 
+/**
+ * Get all option names (including aliases) from a command's options.
+ * Traverses through Map and Subcommands wrappers to find Standard commands.
+ */
+const getParentOptionNames = (self: Instruction): Set<string> => {
+  const names = new Set<string>()
+  const collectFromCommand = (cmd: Instruction): void => {
+    switch (cmd._tag) {
+      case "Standard": {
+        const optionNames = InternalOptions.getNames(cmd.options as InternalOptions.Instruction)
+        for (const name of optionNames) {
+          names.add(name)
+        }
+        break
+      }
+      case "Map": {
+        collectFromCommand(cmd.command)
+        break
+      }
+      case "Subcommands": {
+        collectFromCommand(cmd.parent)
+        break
+      }
+      case "GetUserInput": {
+        break
+      }
+    }
+  }
+  collectFromCommand(self)
+  return names
+}
+
+/**
+ * Extract parent options from anywhere in the args array, specifically
+ * those appearing after a subcommand name. This enables the common CLI
+ * pattern where global/parent options can appear at the end of the command.
+ *
+ * For example: `cli subcommand arg --parent-option value`
+ *
+ * Returns { parentArgs: extracted parent options, remainingArgs: everything else }
+ */
+const extractParentOptionsFromArgs = (
+  args: ReadonlyArray<string>,
+  parentOptionNames: Set<string>,
+  subcommandNames: ReadonlyArray<string>
+): { parentArgs: Array<string>; remainingArgs: Array<string> } => {
+  const parentArgs: Array<string> = []
+  const remainingArgs: Array<string> = []
+
+  let i = 0
+  let foundSubcommand = false
+
+  while (i < args.length) {
+    const arg = args[i]
+
+    // Once we hit a subcommand, check subsequent args for parent options
+    if (!foundSubcommand && subcommandNames.includes(arg)) {
+      foundSubcommand = true
+      remainingArgs.push(arg)
+      i++
+      continue
+    }
+
+    // Only extract parent options AFTER the subcommand has been found
+    // Before the subcommand, args go to remaining (original behavior)
+    if (!foundSubcommand) {
+      remainingArgs.push(arg)
+      i++
+      continue
+    }
+
+    // Check if this is a parent option (starts with - and matches parent option names)
+    if (arg.startsWith("-")) {
+      // Handle --option=value format
+      const equalsIndex = arg.indexOf("=")
+      const optionName = equalsIndex !== -1 ? arg.substring(0, equalsIndex) : arg
+
+      if (parentOptionNames.has(optionName)) {
+        // This is a parent option - extract it
+        if (equalsIndex !== -1) {
+          // --option=value format - single arg contains both
+          parentArgs.push(arg)
+          i++
+        } else {
+          // Check if next arg is the value (not another option, not a subcommand)
+          parentArgs.push(arg)
+          i++
+          if (i < args.length && !args[i].startsWith("-") && !subcommandNames.includes(args[i])) {
+            // Next arg is the value for this option
+            parentArgs.push(args[i])
+            i++
+          }
+        }
+        continue
+      }
+    }
+
+    // Not a parent option - keep in remaining
+    remainingArgs.push(arg)
+    i++
+  }
+
+  return { parentArgs, remainingArgs }
+}
+
 const withDescriptionInternal = (
   self: Instruction,
   description: string | HelpDoc.HelpDoc

packages/cli/test/Command.test.ts

@@ -151,6 +151,40 @@ describe("Command", () => {
           "Cloning repo"
         ])
       }).pipe(Effect.provide(EnvLive), Effect.runPromise))
+
+    it("parent options after subcommand and its args", () =>
+      Effect.gen(function*() {
+        const messages = yield* Messages
+        // --verbose (parent option) appears after "clone repo" (subcommand + args)
+        yield* run(["node", "git.js", "clone", "repo", "--verbose"])
+        assert.deepStrictEqual(yield* messages.messages, [
+          "shared",
+          "Cloning repo"
+        ])
+      }).pipe(Effect.provide(EnvLive), Effect.runPromise))
+
+    it("parent options with alias after subcommand and its args", () =>
+      Effect.gen(function*() {
+        const messages = yield* Messages
+        // -v (parent option alias) appears after "add file" (subcommand + args)
+        yield* run(["node", "git.js", "add", "file", "-v"])
+        assert.deepStrictEqual(yield* messages.messages, [
+          "shared",
+          "Adding file"
+        ])
+      }).pipe(Effect.provide(EnvLive), Effect.runPromise))
+
+    it("parent options both before and after subcommand", () =>
+      Effect.gen(function*() {
+        const messages = yield* Messages
+        // Mix: some parent options before subcommand, parent option after subcommand
+        // Using --verbose before and testing it still works
+        yield* run(["node", "git.js", "--verbose", "clone", "repo"])
+        assert.deepStrictEqual(yield* messages.messages, [
+          "shared",
+          "Cloning repo"
+        ])
+      }).pipe(Effect.provide(EnvLive), Effect.runPromise))
   })
 })