can1357/oh-my-pi · error · CliUsageError

Missing required argument: ${argName}

Error message

Missing required argument: ${argName}

What it means

parse() maps positional arguments to declared arg names in order; if a positional declared `required: true` has no corresponding value on the command line, it throws a CliUsageError naming the missing argument.

Source

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

			}
		}

		// 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) {
				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

View on GitHub (pinned to 9690622007)

Solutions

1. Supply the missing positional argument in declaration order.
2. Quote arguments so empty/space-containing values are not dropped by the shell.
3. Check --help to see the required positional layout.
4. Make the argument optional (required: false) with a default if it should be omittable.

Example fix

// before
cli.parse(['--verbose']); // Missing required argument: file
// after
cli.parse(['--verbose', 'src/index.ts']);

// positionals: [<file>] required
const positionalCount = argv.filter(a => !a.startsWith('--')).length;
if (positionalCount < 1) throw new Error('Usage: omp <file>');

try {
  const { file } = cli.parse(argv);
} catch (err) {
  if (err instanceof CliUsageError && err.message.startsWith('Missing required argument')) {
    console.error(`Usage: ${usageLine}`);
    process.exitCode = 2;
    return;
  }
  throw err;
}

When it happens

Trigger: Calling parse() with too few positionals, e.g. omitting the <file> positional a command declares as required.

Common situations: Copy-pasting a command and dropping a path, scripts passing an empty variable that the shell drops as an argument, or command signatures changed to require an argument between versions.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Expected ${argName} to be one of: ${[...desc.options].join("
• invalid {} argument: {}
• invalid Zero increment value: {}
• --agents must be a positive integer
• --trusted-extension requires a non-empty, non-flag value

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