can1357/oh-my-pi · error · CliUsageError

Expected ${argName} to be one of: ${[...desc.options].join("

Error message

Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"

What it means

parse() enforces the `options` constraint on positional arguments: a required or optional positional whose value is not among the declared allowed strings throws a CliUsageError listing the valid choices.

Source

Thrown at packages/utils/src/cli.ts:280

		for (const [argName, desc] of Object.entries(argDefs)) {
			if (desc.multiple) {
				const val = positionals.slice(posIdx);
				args[argName] = val.length > 0 ? val : undefined;
				posIdx = positionals.length;
			} else {
				const val = positionals[posIdx];
				args[argName] = val;
				posIdx++;
			}
			// Validate required
			if (desc.required && args[argName] === undefined) {
				throw new CliUsageError(`Missing required argument: ${argName}`);
			}
			// Validate options constraint
			const argVal = args[argName];
			if (argVal !== undefined && desc.options && typeof argVal === "string") {
				if (!desc.options.includes(argVal)) {
					throw new CliUsageError(
						`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`,
					);
				}
			}
		}

		return { flags, args, argv: positionals } as never;
	}
}

// ---------------------------------------------------------------------------
// Help rendering
// ---------------------------------------------------------------------------

/** Render full root help: header, default command details, subcommand list. */
export function renderRootHelp(config: CliConfig<CommandMetadata>): void {
	const { bin, version, commands } = config;
	const lines: string[] = [];

View on GitHub (pinned to 9690622007)

Solutions

Use one of the allowed values exactly as listed in the error.
Match case and spelling precisely (comparison is exact string inclusion).
Run --help to see valid positional values.
Extend desc.options in the arg definition if the value should be accepted.

Example fix

// before
cli.parse(['prod']); // Expected env to be one of: dev, staging
// after
cli.parse(['staging']);

Defensive patterns

Strategy: validation

Validate before calling

const allowedEnvs = ['dev', 'staging'];
if (!allowedEnvs.includes(envArg)) {
  throw new Error(`env must be one of: ${allowedEnvs.join(', ')}`);
}

Try / catch

try {
  const { env } = cli.parse(argv);
} catch (err) {
  if (err instanceof CliUsageError && err.message.includes('to be one of')) {
    console.error(err.message);
    process.exitCode = 2;
    return;
  }
  throw err;
}

Prevention

Use exact values from --help for enum-like positionals.
Avoid abbreviations and synonyms for constrained arguments.
Update scripts when allowed value sets change between versions.

When it happens

Trigger: Passing a positional value not in the argument's declared options set, e.g. `<env>` positional given "prod" when options are ["dev","staging"].

Common situations: Users using synonyms or abbreviations for enum-like positionals, case mismatches, or values valid in a previous CLI version.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/a3f6621a97a19b90. Report an issue: GitHub.