feat: support variadic args natively by rexxars · Pull Request #1554 · oclif/core

rexxars · 2026-03-10T20:27:46Z

Native variadic positional arguments

Adds multiple: true support to positional arg definitions, giving commands a type-safe way to accept a variable number of positional arguments.

Before this, the only way to accept extra positional args was strict: false, which bypasses all arg parsing — no type coercion, no validation, no per-arg help text. You just get a raw string array in argv and sort it out yourself.

Now you can do:

static args = {
  files: Args.string({ multiple: true, required: true }),
  dest: Args.string({ required: true }),
}

And get properly typed, validated, parsed values:

$ mycli cp foo.txt bar.txt /tmp/
# args.files = ['foo.txt', 'bar.txt'], args.dest = '/tmp/'

How it works

The variadic arg doesn't have to be last. A shift/pop algorithm (proposed by @Radiergummi in #1346) handles placement anywhere in the arg list:

Non-variadic args before the variadic consume tokens from the front
Non-variadic args after the variadic consume tokens from the back
Everything remaining goes to the variadic arg

Constraints enforced at definition time:

At most one arg per command can be variadic
All args after the variadic must be required: true

Tests

Definition-time validation (multiple variadics rejected, non-required after variadic rejected)
Parsing in every position (first, middle, last, single value, no values, required/optional)
Flags interspersed with variadic args in all configurations
Integer parsing and options validation on variadic args
Help/docopts output with ... suffix
Cache roundtrip

Examples

`cp`

Variable number of args + a trailing, required arg

import {Args, Command, Flags} from '@oclif/core'

export default class Cp extends Command {
  static args = {
    source: Args.string({description: 'Source file(s)', multiple: true, required: true}),
    dest: Args.string({description: 'Destination path', required: true}),
  }

  static description = 'Copy files to a destination (like cp)'

  static examples = [
    '<%= config.bin %> cp foo.txt bar.txt /tmp/',
    '<%= config.bin %> cp *.js ./dist/',
  ]

  static flags = {
    verbose: Flags.boolean({char: 'v', description: 'Show verbose output'}),
  }

  async run() {
    const {args, flags} = await this.parse(Cp)
    if (flags.verbose) {
      this.log('Verbose mode enabled')
    }

    this.log(`Copying ${args.source.length} file(s) to ${args.dest}:`)
    for (const src of args.source) {
      this.log(`  ${src} -> ${args.dest}`)
    }
  }
}

`sum`

import {Args, Command} from '@oclif/core'

export default class Sum extends Command {
  static args = {
    numbers: Args.integer({description: 'Numbers to sum', multiple: true, required: true}),
  }

  static description = 'Sum a list of numbers'

  async run() {
    const {args} = await this.parse(Sum)
    const total = args.numbers.reduce((a, b) => a + b, 0)
    this.log(`${args.numbers.join(' + ')} = ${total}`)
  }
}

Resolved issues

Closes First-class support for Variadic Arguments #1346

Update help rendering to add '...' suffix per-arg based on the `multiple` property, instead of only using command-level `strict === false`. The existing strict===false behavior is preserved as a fallback for backward compatibility.

Rewrites _args() in parse.ts to support variadic args using a shift/pop algorithm: pre-variadic args consume from the front, post-variadic args consume from the back, and everything remaining goes to the variadic arg as an array. Also updates validate.ts to skip UnexpectedArgsError when a variadic arg is present.

Add TypeScript overloads to ArgDefinition so that Args.string({ multiple: true }) correctly types the return as Arg<T[]> instead of Arg<T>. This mirrors how FlagDefinition handles multiple: true with its overloads.

Break apart _args() by extracting parseArgInput, applyDefault, and tryStdin helpers. Inline the variadic path instead of a separate method to avoid passing 7 parameters. Remove "original logic" comments.

Verify that variadic args show ... suffix in USAGE line: - last position, first with trailing required, middle position - optional variadic shows [FILES...] - non-variadic siblings don't get the suffix

The cacheArgs function wasn't including the `multiple` property when caching arg metadata, which caused help text to miss the `...` suffix for variadic args when loaded from the manifest cache.

Verify that the shift/pop parsing algorithm correctly handles flags placed between positional arguments in various configurations: leading required + variadic, variadic + trailing required, both, and boolean flags mixed in.

Radiergummi

oh, this is amazing. Thank you so much for taking care of this!

jfeingold35 · 2026-03-12T18:09:50Z

Thanks for submitting this. I'll get it reviewed and QA'd, and let you know if anything needs to change.

jfeingold35 · 2026-03-13T14:30:47Z

+          await parse(['a', 'b'], {
+            args: {
+              first: Args.string({multiple: true}),
+              second: Args.string({multiple: true}),


Q: Just to make sure that this is actually failing specifically because it's two variadics and not because it's a non-required arg following a variadic, should second be required: true?

Valid - 8378f8b makes this change.

jfeingold35 · 2026-03-13T14:34:05Z

+    })
+
+    describe('parsing', () => {
+      it('variadic arg as last arg', async () => {


Just to be as thorough as possible, should this perhaps be split into two different tests called variadic as only arg and variadic as last arg?

Agreed - the test had a single variadic arg with no other args, so it was actually "only arg" not "last arg". I've included a few more test cases in 8378f8b

jfeingold35 · 2026-03-13T14:37:31Z

+      it('variadic arg in the middle', async () => {
+        const out = await parse(['tar', 'a', 'b', 'c', './out.tar'], {
+          args: {
+            format: Args.string({required: true}),


Your description of the algorithm indicates that args after the variadic have to be required, but don't the ones before it have to be required as well, otherwise it's unclear which arg to assign parameters to?

You're right - arguments before a variadic arg were read left to right. If one of those were optional, the parser had no clear way to tell whether the user skipped it or meant their value for the next arg. So the behavior was consistent, but confusing. The validation in only checked args after a variadic one, and should also check args before it. 454ae3d includes a fix for this and also provides clearer messages (as you requested below)

jfeingold35 · 2026-03-16T15:05:37Z

@rexxars , I've left some comments. If you could please address them, then we should be good to move on to the QA stage.

jfeingold35 · 2026-03-16T17:56:02Z

+        variadicArgFound = true
+      } else if (variadicArgFound && !arg.required) {
+        // All args after a variadic arg must be required
+        throw new InvalidArgsSpecError({


This error does nothing to indicate that the specific problem is a non-required arg following a variadic arg; it just says "invalid argument spec" and then lists the arguments. Could we get a more informative message here?

Yep. 454ae3d adds clearer messages indicating what specifically is invalid :)

jfeingold35 · 2026-03-18T17:23:21Z

@rexxars , thank you for addressing the feedback. I'll conduct another review and do the necessary QA, and we can hopefully get this merged in the near future.

jfeingold35 · 2026-03-18T19:48:14Z

@rexxars , the code looks good, and I've done the following QA checks:

Lone variadic (works as expected)
Variadic w/ normal args before and after (works as expected, args must be required to work correctly)
Variadic w/ flags interspersed (notably, when a flag is multiple: true, you need to use -- to explicitly terminate the flag's list and resume the variadic list).
Help text shows up as expected

However, I've noticed one gap: A variadic argument's default can still only be a single string, not an array of strings. In my opinion, this isn't a blocker, and I'm willing to merge what you have now. However, if you'd like to implement that here and include it as part of this PR, then I'm happy to wait. Let me know how you'd like to proceed.

rexxars · 2026-03-18T21:29:53Z

However, I've noticed one gap: A variadic argument's default can still only be a single string, not an array of strings. In my opinion, this isn't a blocker, and I'm willing to merge what you have now. However, if you'd like to implement that here and include it as part of this PR, then I'm happy to wait. Let me know how you'd like to proceed.

Pushed a commit for this - but needs some careful eyes, typescript defs are getting a little unwieldy 😅

rexxars added 9 commits March 10, 2026 12:37

feat: add multiple property to ArgProps interface

fb76263

feat: show ... suffix for variadic args in help text

fc53652

Update help rendering to add '...' suffix per-arg based on the `multiple` property, instead of only using command-level `strict === false`. The existing strict===false behavior is preserved as a fallback for backward compatibility.

feat: add definition-time validation for variadic arg constraints

20d2543

feat: add ArgDefinition overloads for variadic arg return types

6fea593

Add TypeScript overloads to ArgDefinition so that Args.string({ multiple: true }) correctly types the return as Arg<T[]> instead of Arg<T>. This mirrors how FlagDefinition handles multiple: true with its overloads.

refactor: extract helpers from _args()

2b8a472

Break apart _args() by extracting parseArgInput, applyDefault, and tryStdin helpers. Inline the variadic path instead of a separate method to avoid passing 7 parameters. Remove "original logic" comments.

test: add help output tests for variadic args

06811f4

Verify that variadic args show ... suffix in USAGE line: - last position, first with trailing required, middle position - optional variadic shows [FILES...] - non-variadic siblings don't get the suffix

fix: include multiple property in cached arg metadata

32b4bb7

The cacheArgs function wasn't including the `multiple` property when caching arg metadata, which caused help text to miss the `...` suffix for variadic args when loaded from the manifest cache.

test: add coverage for flags interspersed with variadic args

606fa37

Verify that the shift/pop parsing algorithm correctly handles flags placed between positional arguments in various configurations: leading required + variadic, variadic + trailing required, both, and boolean flags mixed in.

salesforce-cla Bot added the cla:signed label Mar 10, 2026

Radiergummi approved these changes Mar 12, 2026

View reviewed changes

jfeingold35 reviewed Mar 13, 2026

View reviewed changes

jfeingold35 reviewed Mar 16, 2026

View reviewed changes

rexxars added 2 commits March 17, 2026 23:19

test: more thoroughly test variadic arg combinations

8378f8b

fix: provide clearer messages on invalid variadic args

454ae3d

jfeingold35 previously approved these changes Mar 18, 2026

View reviewed changes

feat: allow array of default values for varargs

da42b29

rexxars dismissed jfeingold35’s stale review via da42b29 March 18, 2026 21:27

jfeingold35 approved these changes Mar 19, 2026

View reviewed changes

jfeingold35 merged commit 4c6b3d7 into oclif:main Mar 19, 2026
87 checks passed

jfeingold35 mentioned this pull request Mar 19, 2026

docs: documentation for new arg-level property, multiple oclif/oclif.github.io#283

Merged

rexxars deleted the feat/native-variadic-args branch March 20, 2026 15:22

Conversation

rexxars commented Mar 10, 2026

Native variadic positional arguments

How it works

Tests

Examples

cp

sum

Resolved issues

Uh oh!

Radiergummi left a comment

Choose a reason for hiding this comment

Uh oh!

jfeingold35 commented Mar 12, 2026

Uh oh!

jfeingold35 Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

rexxars Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

jfeingold35 Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

rexxars Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

jfeingold35 Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

rexxars Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jfeingold35 commented Mar 16, 2026

Uh oh!

jfeingold35 Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

rexxars Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

jfeingold35 commented Mar 18, 2026

Uh oh!

jfeingold35 commented Mar 18, 2026

Uh oh!

rexxars commented Mar 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`cp`

`sum`

rexxars Mar 18, 2026 •

edited

Loading