The package keeps Yargs out of @ariestools/cli-kit while routing parser help, version, validation errors, asynchronous failures, and exits through the core ProcessHost boundary. This makes a configured CLI safe to exercise with a recording host instead of allowing Yargs to write to the ambient console or terminate the test process.

Help, version, and completion output still end the run the way Yargs' own process exit would. Routing through the host means Yargs no longer ends the process; it records the exit and keeps going. So once Yargs exits zero, runYargsApplication skips every middleware registered on the parser, including .check() callbacks. A root --help, -h, or bare help therefore never reaches an application's configuration middleware, and app bogus --help prints help rather than Unknown command: bogus. Root help also waits for an async $0 builder: Yargs prints that help only after the builder settles, which would otherwise be after the parse has finished. Failure exits are unchanged; see the handler note under Rejecting unknown commands.

runYargsApplication accepts an optional mapFailureToExitCode mapper applied to parser and handler failures alike: the mapper receives the failure origin ('parse' for validation failures, 'handler' for handler or middleware rejections), returning a number selects the exit code, undefined retains the default exit code one. A mapper that throws, or returns a code outside the integer range 0–255, falls back to exit code one. Intentional ProcessExitError exits pass through untouched.

Failure output is scoped by that same origin. A parse-origin failure (a Yargs validation or usage error, including one raised by rejectUnknownCommands) still prints the usage/help block, because the caller mis-invoked the CLI. A handler-origin failure (a thrown command handler or middleware — for example a mapped configuration error that exits 78) prints the raw error to stderr, including its stack when present, with no usage dump. Production keeps full diagnostics so fatal handler failures remain diagnosable; only the noisy usage block is suppressed. The exit code and mapFailureToExitCode contract are unchanged; only what is printed per origin differs.

Repeated options

configureCliSurface applies one repeated-option policy to every consumer, and withRepeatableOptions(parser) applies the same policy to a parser assembled without it:

an option declared array: true / type: 'array' collects every occurrence (--tag a --tag b gives ['a', 'b']), and a variadic positional (serve [files..]) keeps every value;
an option declared nargs: n with n > 1 keeps its last n values;
every other declared option resolves last-wins under all of its spellings — aliases, camelCase and hyphenated keys, dotted keys — so --out a --out b hands the handler 'b' rather than an array.

The policy keeps yargs' default duplicate-arguments-array: true and restores last-wins in a before-validation middleware, so choices, .check(...), coerce, and the handler see only the surviving value: --mode bogus --mode safe passes choices: ['fast', 'safe'], and --mode safe --mode bogus fails it. Turning duplicate-arguments-array off is no substitute under yargs 18: it keeps only the last occurrence of an array option, truncates a variadic positional to its last value, and can leave an array option's camelCase key disagreeing with its hyphenated key.

import { runYargsApplication, withRepeatableOptions } from '@ariestools/cli-kit-yargs'

await runYargsApplication({
  host,
  configure: parser => withRepeatableOptions(parser.scriptName('app'))
    .command(serveCommand)
    .strictOptions()
    .help(),
})

Three constraints keep the policy intact:

Leave duplicate-arguments-array unset in any .parserConfiguration(...) call, including one in a configureCliSurface customize hook. That call replaces yargs' configuration wholesale, and an unset key keeps yargs' default true; withRepeatableOptions never calls it, so it cannot discard settings applied before it.
Apply withRepeatableOptions before declaring any option with coerce: yargs runs coerce functions as middleware in registration order, so one registered earlier receives the uncollapsed array.
Declare a variadic positional with .positional(...), which records it as an array option (.strictOptions() rejects an undeclared positional anyway). Naming it only through .coerce(...) or a non-array .option(...) declares a single-value option instead, whose values collapse to the last one.

Rejecting unknown commands

.strictCommands() cannot flag an unknown command once a $0 default command is registered — the default command consumes the stray token as a positional and Yargs accepts it silently. rejectUnknownCommands(parser, commands) closes that gap with a .check() that compares each leftover positional against the command names (and aliases) declared by commands, throwing a parse-origin Unknown command: <token> for anything unrecognized. A bare invocation, a registered command with its options, and the help/$0 paths are left untouched. Apply it after every .command(...) registration and before .help(), passing the same array you registered:

import { rejectUnknownCommands, runYargsApplication } from '@ariestools/cli-kit-yargs'

await runYargsApplication({
  host,
  mapFailureToExitCode: (_error, origin) => (origin === 'parse' ? 64 : undefined),
  configure: (parser) => {
    let configured = parser.scriptName('app')
    for (const command of commands) configured = configured.command(command)
    return rejectUnknownCommands(configured, commands).help().version(version)
  },
})

Every non-empty leftover token is inspected regardless of its runtime type. Yargs types argv._ as (string | number)[] and, with its default parse-positional-numbers enabled, coerces a bare numeric token to a JS number — so app 0, app 123, and app -5 are flagged as Unknown command: 0 (and so on) just like a word. No .parserConfiguration({ 'parse-positional-numbers': false }) workaround is needed to catch a numeric stray. The message echoes the coerced value rather than the raw text, so an exotic numeric literal is reported normalized — 1e3 reads Unknown command: 1000, 0x10 reads 16, 1.50 reads 1.5 — because Yargs has already coerced by the time a .check() runs. Rejection is correct in every case; only the echoed text differs. An empty token (app "") is the one exclusion: it names no command and falls through to $0.

Four constraints keep the check accurate.

The commands array must equal the set registered on the parser — the accepted-name set is derived from it, not read back from the parser, so any drift silently rejects a valid command or accepts an unhandled one.
Every accepted positional must be declared in its command string (serve <file>, serve [file], serve [files..]): Yargs consumes declared positionals out of argv._ into named keys before the check runs — including numeric-valued ones, so serve <port> invoked as serve 8080 is unaffected — but a command that reads ad-hoc positionals it never declared would leave them in argv._ and see the first rejected as Unknown command: <value>.
A subcommand registered inside a parent command's builder must also appear in commands. Yargs leaves both tokens in argv._ (db migrate yields ['db', 'migrate']), so a nested name missing from the array is rejected as Unknown command: migrate. Passing the nested modules alongside the top-level ones fixes that, at the cost of a flat accepted-name set: the nested name is then also accepted at the top level, where it falls through to $0.
Tokens after a -- separator are not passthrough unless the caller enables .parserConfiguration({ 'populate--': true }). Yargs leaves populate-- off by default, which merges those tokens into argv._ rather than argv['--'], so app local -- raw is rejected as Unknown command: raw (and app local -- 5 as Unknown command: 5). Enabling populate-- routes them to argv['--'], out of argv._ and out of this check's reach.

For an unknown token Yargs runs the failing check first, then still invokes the matched command's handler before surfacing the parse failure — the $0 default command for a bare stray token, and the named command for app publish 0. parseAsync awaits an async handler to completion, so its side effects commit before the flagged exit. Keep any handler reachable alongside a stray token side-effect-free (for $0, printing a usage block is the intended shape).

Use environmentToYargsConfig when an application owns config-file loading and wants to replace Yargs' process-global .env() lookup with an explicitly supplied environment. The resulting flat dotted object preserves Yargs' environment key normalization and can be passed to .config() before parsing:

import { createNodeProcessHostWithDotEnv } from '@ariestools/cli-kit-node'
import { environmentToYargsConfig, runYargsApplication } from '@ariestools/cli-kit-yargs'

const host = createNodeProcessHostWithDotEnv()

await runYargsApplication({
  host,
  configure: parser => parser
    .config(environmentToYargsConfig(host.environment, 'XL1'))
    .scriptName('xl1')
    .command(commands)
    .help()
    .version(version),
})

Load dotenv files through @ariestools/cli-kit-node (loadDotEnvFile / createNodeProcessHostWithDotEnv) so values reach host.environment without mutating process.env. This conversion preserves command-line-over-environment precedence, but it is not a general substitute for Yargs-native config-file options: Yargs ranks config objects below config files, and treats a top-level extends key in a config object specially. Such applications should resolve those precedence and reserved-key rules before passing the object to .config().