Using vitest complete -- for wrapper CLI completions

[RSS1102]

We’d like to add Tab completion to Vite+’s vp test voidzero-dev/vite-plus#2953 by querying the corresponding Vitest version through vitest complete -- <args...> and adapting its output to our existing shell completion system.

For example, vp test --reporter <Tab> would query:

vitest complete -- --reporter ''
# default<TAB>Default reporter
# …
# :4

1. Is this a supported integration interface for wrapper CLIs?
2. Can we rely on the output format—tab-separated candidates and descriptions, followed by a directive line—with incompatible changes limited to major releases?

If not, what integration approach would you recommend?

[sheremet-va]

vitest complete is provided by https://npmx.dev/package/@bomb.sh/tab I'm not even sure how it works, I thought it's meant for your terminal shells 🤔

Vitest doesn't control its output, but we don't plan to remove/update it. Vitest exposes createCLI from vitest/node, maybe you can use it to get the values? 🤔

[saraeloop]

Yeah, adding tab completion on top of another CLI gets tricky fast. Vitest 5.0.5 handles it, and I think @sheremet-va's createCLI() suggestion gets you most of the way.

For flags, use createCLI(). It's exported from vitest/node and documented. It gives you every command and option with its description, and it always matches the installed Vitest version:

import { createCLI } from 'vitest/node'
const cli = createCLI()
cli.globalCommand.options // every option, with names and descriptions

For values, there's a gap. createCLI() doesn't include value candidates like the reporter names. Those come from an internal setupTabCompletions (source) that isn't exported. In 5.0.5, only six options have values: --environment, --pool, --reporter, --silent, --coverage.reporter and --browser.name.

On relying on vitest complete: I couldn't find any documentation that makes it a contract for wrapper CLIs. Vitest bundles @bomb.sh/tab (a pre-1.0 0.0.x version), and the format comes from there. It follows Cobra's __complete style: candidate, tab, description, then a :<n> directive line (:4 means "no file completion"). Since tab is bundled, an upgrade could change the format in any Vitest release, so I wouldn't count on breaking changes being limited to majors unless the Vitest team commits to that.

Two things I noticed while testing:

• The reporter values have drifted a bit. agent, minimal, blob, tree and github-actions exist in 5.0.5, but completion doesn't offer them.
• In my 5.0.5 test, values only completed at the top level. vitest complete -- --pool '' worked, but vitest complete -- run --pool '' returned just :4. So if vp test maps to vitest run, leave out the run when querying.

What I'd do: use createCLI() for flags. For those six options, either keep a small value table in Vite+, or ask vitest complete for just those and show no values if the output doesn't parse. Longer term, if Vitest attached the values to the option definitions (or exported that table), createCLI() could cover everything.

[RSS1102]

@sheremet-va @saraeloop
Thanks for the explanation! I’ll try implementing this with createCLI().
Just to confirm: is read-only traversal of its public command and option fields an intended use?

[saraeloop]

That one's really for @sheremet-va, since only the Vitest team can say what's intended. If it helps, you can see how the fields are declared in node_modules/vitest/dist/node.d.ts. Vitest bundles cac and inlines its types there, so in 5.0.5 commands, globalCommand and each command's options (rawName, description, config) are regular public fields, not private ones. So read-only traversal at least matches the published types in 5.0.5.

The usual caveat applies, though: since cac is bundled, a cac upgrade inside Vitest could change those shapes. I'd keep the traversal in one small adapter so it's easy to update if that ever happens. Hope it helps!

[sheremet-va]

Generally speaking, we don’t consider CLI output to be stable between releases, but in practice it doesn’t happen often, and the “vitest complete” output is not even controlled by the team, it’s an external package.