Fix CLI positional argument overflow

[hsubra89]

A positional variadic with a max stopped consuming values once it reached the limit, but any remaining operands were ignored after parsing finished.

For example:

const upload = Command.make("upload", {
  files: Argument.string("file").pipe(
    Argument.variadic({ max: 2 })
  )
})

Running:

upload a.txt b.txt c.txt

previously succeeded with ["a.txt", "b.txt"] and silently discarded c.txt. It now fails with:

Unexpected positional argument: "c.txt"

The fix rejects positional operands left over after the complete command has been parsed.

Variadics can still pass operands to positional arguments declared after them, so this remains valid:

const copy = Command.make("copy", {
  sources: Argument.string("source").pipe(
    Argument.variadic({ max: 2 })
  ),
  destination: Argument.string("destination")
})

copy a.txt b.txt output/

Partial parsing for shared flags and parent command context also continues to preserve operands, since those may belong to the active command or subcommand.

This PR was raised with the help of Codex ( GPT-5.6-Sol-high )

Summary by CodeRabbit

• New Features
  • Added a dedicated CLI error for unexpected leftover positional arguments, with clear messaging for one or multiple extra operands.
• Bug Fixes
  • CLI parsing now rejects unconsumed positional arguments after command/context parsing, including cases beyond configured variadic limits.
  • Refined shared and inherited option parsing so leftover tokens are handled consistently when combining parsers.
• Tests
  • Expanded coverage for unexpected-argument scenarios and verified error message formatting.

[changeset-bot]

🦋 Changeset detected

Latest commit: ec442eb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 28 packages

Name	Type
effect	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/vitest	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/docgen	Patch
@effect/openapi-generator	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 27f4a25f-4353-4bdd-bd5c-0e334702b467

📥 Commits

Reviewing files that changed from the base of the PR and between 4bda315 and ec442eb.

📒 Files selected for processing (5)

• .changeset/fix-cli-unexpected-arguments.md
• packages/effect/src/unstable/cli/CliError.ts
• packages/effect/src/unstable/cli/Command.ts
• packages/effect/src/unstable/cli/internal/command.ts
• packages/effect/test/unstable/cli/Errors.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• .changeset/fix-cli-unexpected-arguments.md
• packages/effect/src/unstable/cli/Command.ts
• packages/effect/test/unstable/cli/Errors.test.ts
• packages/effect/src/unstable/cli/CliError.ts
• packages/effect/src/unstable/cli/internal/command.ts

---

📝 Walkthrough

Walkthrough

CLI parsing now preserves leftover tokens during shared and context parsing, while top-level parsing reports unconsumed positional arguments with a new UnexpectedArgument error. The error is included in public CLI unions and covered by parsing and message-format tests.

Changes

CLI unexpected argument handling

Layer / File(s)	Summary
UnexpectedArgument error contract packages/effect/src/unstable/cli/CliError.ts	Adds the schema-tagged UnexpectedArgument error, includes it in exposed CLI error unions, and formats single or multiple unexpected positional arguments.
Parser leftover handling packages/effect/src/unstable/cli/internal/command.ts, packages/effect/src/unstable/cli/Command.ts	Propagates remaining arguments from parseParams, rejects leftovers by default, and allows shared-flag and context parsers to retain them.
UnexpectedArgument parsing tests and release note packages/effect/test/unstable/cli/Errors.test.ts, .changeset/fix-cli-unexpected-arguments.md	Tests leftover fixed and bounded variadic arguments, subsequent argument consumption, and error message formatting; documents the patch release behavior change.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: bug

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[IMax153]

I think this is the behavior that we want / expect, no?

[hsubra89]

I think this is the behavior that we want / expect, no?

Just to clarify, are you asking if the original behaviour was correct?

The core problem here is that the original implementation was silently dropping user input - especially when a max num was defined.

Codex also states that the v3 @effect/cli implementation did fail this case with a Received unknown argument: '<value>' error, but I didn't verify that myself.

[github-actions]

Bundle Size Analysis

File Name	Current Size	Previous Size	Difference
basic.ts	6.64 KB	6.64 KB	0.00 KB (0.00%)
batching.ts	9.42 KB	9.42 KB	0.00 KB (0.00%)
brand.ts	6.20 KB	6.20 KB	0.00 KB (0.00%)
cache.ts	10.13 KB	10.13 KB	0.00 KB (0.00%)
config.ts	19.08 KB	19.08 KB	+0.00 KB (+0.02%)
differ.ts	18.41 KB	18.41 KB	0.00 KB (0.00%)
http-client.ts	20.73 KB	20.73 KB	0.00 KB (0.00%)
logger.ts	10.30 KB	10.30 KB	0.00 KB (0.00%)
metric.ts	8.56 KB	8.56 KB	0.00 KB (0.00%)
optic.ts	7.41 KB	7.41 KB	0.00 KB (0.00%)
pubsub.ts	14.17 KB	14.17 KB	0.00 KB (0.00%)
queue.ts	11.10 KB	11.10 KB	0.00 KB (0.00%)
schedule.ts	10.28 KB	10.28 KB	0.00 KB (0.00%)
schema-class.ts	18.16 KB	18.16 KB	0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts	27.31 KB	27.31 KB	+0.00 KB (+0.01%)
schema-representation-roundtrip.ts	24.16 KB	24.16 KB	0.00 KB (0.00%)
schema-string-transformation.ts	12.68 KB	12.68 KB	0.00 KB (0.00%)
schema-string.ts	10.36 KB	10.36 KB	0.00 KB (0.00%)
schema-template-literal.ts	14.38 KB	14.38 KB	0.00 KB (0.00%)
schema-toArbitraryLazy.ts	20.94 KB	20.93 KB	+0.00 KB (+0.02%)
schema-toCodeDocument.ts	23.42 KB	23.42 KB	0.00 KB (0.00%)
schema-toCodecJson.ts	18.30 KB	18.30 KB	0.00 KB (0.00%)
schema-toEquivalence.ts	18.01 KB	18.01 KB	0.00 KB (0.00%)
schema-toFormatter.ts	17.86 KB	17.86 KB	0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts	21.49 KB	21.49 KB	0.00 KB (0.00%)
schema-toRepresentation.ts	18.55 KB	18.55 KB	0.00 KB (0.00%)
schema.ts	17.43 KB	17.43 KB	0.00 KB (0.00%)
stm.ts	12.07 KB	12.07 KB	0.00 KB (0.00%)
stream.ts	9.36 KB	9.36 KB	0.00 KB (0.00%)