can1357/oh-my-pi · error · CliUsageError

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

Error message

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

What it means

parse() enforces the `options` constraint on string flags: if the flag declares an allowed set and the provided value is not in it, a CliUsageError listing the valid choices is thrown.

Source

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

				if (raw === undefined || typeof raw === "boolean") {
					flags[name] = desc.default ?? undefined;
				} else {
					const n = Number.parseInt(raw as string, 10);
					if (Number.isNaN(n)) {
						throw new CliUsageError(`Expected integer for --${name}, got "${raw}"`);
					}
					flags[name] = n;
				}
			} else if (desc.kind === "boolean") {
				flags[name] =
					raw !== undefined ? Boolean(raw) : desc.default !== undefined ? Boolean(desc.default) : undefined;
			} else {
				// string
				const val = raw !== undefined && typeof raw !== "boolean" ? raw : (desc.default ?? undefined);
				// Validate options constraint
				if (val !== undefined && desc.options && !Array.isArray(val)) {
					if (!desc.options.includes(val as string)) {
						throw new CliUsageError(
							`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`,
						);
					}
				}
				flags[name] = val;
			}
			// Validate required
			if (desc.required && flags[name] === undefined) {
				throw new CliUsageError(`Missing required flag: --${name}`);
			}
		}

		// Map positionals to named args in declaration order and validate
		const args: Record<string, unknown> = {};
		let posIdx = 0;
		for (const [argName, desc] of Object.entries(argDefs)) {
			if (desc.multiple) {
				const val = positionals.slice(posIdx);

View on GitHub (pinned to 9690622007)

Solutions

1. Use one of the listed allowed values exactly as shown in the error message.
2. Match the case of the declared options (comparison is case-sensitive).
3. Run --help to see the current allowed values.
4. If the value should be legal, extend desc.options in the flag definition.

Example fix

// before
cli.parse(['--format', 'yaml']); // not in options
// after
cli.parse(['--format', 'json']);

const allowed = ['json', 'text'];
if (!allowed.includes(formatValue)) {
  throw new Error(`--format must be one of: ${allowed.join(', ')}`);
}

try {
  const { format } = 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;
}

When it happens

Trigger: Passing a value to an enum-constrained flag that is not one of the declared options, e.g. `--format xml` when options are ["json","text"], or a value that differs only in case.

Common situations: Users guessing valid values, mixing up case (--Level vs level), or using values valid in an older CLI version whose enum was renamed.

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

• invalid {} argument: {}
• invalid Zero increment value: {}
• --agents must be a positive integer
• --trusted-extension requires a non-empty, non-flag value
• Invalid value: ${rawValue}. Valid values: ${valid.join(", ")

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