test/docs(cli): document and test parent options after subcommand arguments by cevr · Pull Request #6000

test/docs(cli): document and test parent options after subcommand arguments by cevr · Pull Request #6000 · Effect-TS/effect

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>

cevr and others added 5 commits

February 6, 2026 13:04

…on extraction

Child wins for shared options after subcommand (matches CLI conventions).
Boolean parent options no longer steal the next token as a value.
Adds comprehensive descriptor-level and integration tests.

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

…ions

The FAQ and usage sections incorrectly stated options must appear before
positional args and subcommands. Updated to reflect the new behavior and
document shared option resolution (child wins after subcommand).

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

…r section

Show actual @effect/cli code for flexible option placement and shared
option resolution instead of referencing git behavior.

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

The extractParentOptionsFromArgs mechanism and all supporting helpers
(getParentOptionInfo, collectBooleanNames, getChildOptionNames) are
redundant — PR Effect-TS#5983's parseCommandLine scan + child leftover re-parse
path already handles parent options after subcommand args, including
shared option resolution and boolean awareness. 177/177 tests pass
without any of this code.

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

Tests the pattern where a parent command provides shared options (like
--verbose) as a service to subcommands. Verifies parent options work
when placed after subcommand names and subcommand options.

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

cevr changed the title ~~fix(cli): allow parent options after subcommand arguments~~ test/docs(cli): document and test parent options after subcommand arguments

Feb 6, 2026