can1357/oh-my-pi · error · CliUsageError

error instanceof Error ? error.message : String(error)

Error message

error instanceof Error ? error.message : String(error)

What it means

parse() wraps failures from Node's util.parseArgs (invalid option syntax, unknown flags in strict mode, unexpected positional values) into a CliUsageError whose message is the underlying parser message. It signals the command line itself was malformed, not that the program failed at runtime.

Source

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

			if (desc.multiple) opt.multiple = true;
			if (desc.default !== undefined) {
				opt.default = desc.kind === "boolean" ? Boolean(desc.default) : String(desc.default);
			}
			options[name] = opt;
		}

		// strict=false when command declares args (positionals must pass through)
		// or when the command itself opts out
		const { values: rawValues, positionals } = (() => {
			try {
				return nodeParseArgs({
					args: this.argv,
					options,
					allowPositionals: true,
					strict,
				});
			} catch (error) {
				throw new CliUsageError(error instanceof Error ? error.message : String(error));
			}
		})();

		// Convert raw values to proper types and validate
		const flags: Record<string, unknown> = {};
		for (const [name, desc] of Object.entries(flagDefs)) {
			const raw = rawValues[name];
			if (desc.kind === "integer") {
				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") {

View on GitHub (pinned to 9690622007)

Solutions

1. Fix the offending flag/value per the wrapped parseArgs message in the error text.
2. Run the CLI with --help or check the flag definitions passed to parse() to confirm accepted flags.
3. Quote values containing spaces or special shell characters.
4. If you own the CLI, mark newly-optional flags lenient (strict: false) or register them in flagDefs.

Example fix

// before
cli.parse(['--verbos', 'x']); // CliUsageError: Unknown option '--verbos'
// after
cli.parse(['--verbose', 'x']);

// pre-validate argv against the CLI's declared flags before parsing
const known = new Set(['--verbose', '--config', '--format']);
const unknown = args.filter(a => a.startsWith('--') && !known.has(a.split('=')[0]));
if (unknown.length) console.error(`Unknown flags: ${unknown.join(' ')}`);

try {
  const parsed = cli.parse(argv);
} catch (err) {
  if (err instanceof CliUsageError) {
    console.error(`Usage error: ${err.message}`);
    process.exitCode = 2; // usage exit code, not a crash
    return;
  }
  throw err;
}

When it happens

Trigger: Calling cli.parse() with an unknown flag in strict mode, a flag given without its required value, an option value where a boolean was declared, or a positional in a spot that conflicts with the declared args.

Common situations: Users typo a flag (--verbos instead of --verbose), pass `--flag=value` where the grammar expects space-separated values, or scripts pass stale flags after the CLI surface changed between versions.

Related errors

• Usage: /export [--themes] [path]
• ${flag} requires a value
• Unknown security plan option: ${token}
• Unknown security cloud option: ${token}
• Usage: /security cloud <scans|start|status|pull>

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