can1357/oh-my-pi · error · CliUsageError

Missing required flag: --${name}

Error message

Missing required flag: --${name}

What it means

parse() checks every flag declared `required: true` after value conversion; if the resolved value is still undefined (flag absent and no default), it throws a CliUsageError naming the missing flag.

Source

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

			} 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);
				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) {

View on GitHub (pinned to 9690622007)

Solutions

1. Provide the missing flag on the command line as named in the error.
2. Set a default in the flag definition so it becomes optional.
3. Check --help for required flags before running.
4. Update automation scripts to pass flags added as required in newer versions.

Example fix

// before
cli.parse([]); // Missing required flag: --config
// after
cli.parse(['--config', './omp.json']);

// ensure required flags are present before invoking
const required = ['--config'];
const missing = required.filter(f => !argv.includes(f) && !argv.some(a => a.startsWith(f + '=')));
if (missing.length) throw new Error(`Missing flags: ${missing.join(', ')}`);

try {
  const parsed = cli.parse(argv);
} catch (err) {
  if (err instanceof CliUsageError && err.message.startsWith('Missing required flag')) {
    cli.printHelp();
    process.exitCode = 2;
    return;
  }
  throw err;
}

When it happens

Trigger: Invoking a command that omits a flag declared with required: true and no default, e.g. calling parse() without --config when the definition requires it.

Common situations: Users skipping a mandatory flag, scripts written against an older CLI where the flag was optional, or alias mismatch (using a short alias not registered for the required flag).

Related errors

• invalid {} argument: {}
• invalid Zero increment value: {}
• --agents must be a positive integer
• --trusted-extension requires a non-empty, non-flag value
• --trusted-extension requires an absolute path: ${trustedPath

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