{"record":{"id":"c2d5bcca9d195b3f","repo":"can1357/oh-my-pi","slug":"missing-required-flag-name","errorCode":null,"errorMessage":"Missing required flag: --${name}","messagePattern":"Missing required flag: --(.+?)","errorType":"validation","errorClass":"CliUsageError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/cli.ts","lineNumber":255,"sourceCode":"\t\t\t} else if (desc.kind === \"boolean\") {\n\t\t\t\tflags[name] =\n\t\t\t\t\traw !== undefined ? Boolean(raw) : desc.default !== undefined ? Boolean(desc.default) : undefined;\n\t\t\t} else {\n\t\t\t\t// string\n\t\t\t\tconst val = raw !== undefined && typeof raw !== \"boolean\" ? raw : (desc.default ?? undefined);\n\t\t\t\t// Validate options constraint\n\t\t\t\tif (val !== undefined && desc.options && !Array.isArray(val)) {\n\t\t\t\t\tif (!desc.options.includes(val as string)) {\n\t\t\t\t\t\tthrow new CliUsageError(\n\t\t\t\t\t\t\t`Expected --${name} to be one of: ${[...desc.options].join(\", \")}; got \"${val}\"`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tflags[name] = val;\n\t\t\t}\n\t\t\t// Validate required\n\t\t\tif (desc.required && flags[name] === undefined) {\n\t\t\t\tthrow new CliUsageError(`Missing required flag: --${name}`);\n\t\t\t}\n\t\t}\n\n\t\t// Map positionals to named args in declaration order and validate\n\t\tconst args: Record<string, unknown> = {};\n\t\tlet posIdx = 0;\n\t\tfor (const [argName, desc] of Object.entries(argDefs)) {\n\t\t\tif (desc.multiple) {\n\t\t\t\tconst val = positionals.slice(posIdx);\n\t\t\t\targs[argName] = val.length > 0 ? val : undefined;\n\t\t\t\tposIdx = positionals.length;\n\t\t\t} else {\n\t\t\t\tconst val = positionals[posIdx];\n\t\t\t\targs[argName] = val;\n\t\t\t\tposIdx++;\n\t\t\t}\n\t\t\t// Validate required\n\t\t\tif (desc.required && args[argName] === undefined) {","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/cli.ts#L237-L273","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Provide the missing flag on the command line as named in the error.","Set a default in the flag definition so it becomes optional.","Check --help for required flags before running.","Update automation scripts to pass flags added as required in newer versions."],"exampleFix":"// before\ncli.parse([]); // Missing required flag: --config\n// after\ncli.parse(['--config', './omp.json']);","handlingStrategy":"validation","validationCode":"// ensure required flags are present before invoking\nconst required = ['--config'];\nconst missing = required.filter(f => !argv.includes(f) && !argv.some(a => a.startsWith(f + '=')));\nif (missing.length) throw new Error(`Missing flags: ${missing.join(', ')}`);","typeGuard":null,"tryCatchPattern":"try {\n  const parsed = cli.parse(argv);\n} catch (err) {\n  if (err instanceof CliUsageError && err.message.startsWith('Missing required flag')) {\n    cli.printHelp();\n    process.exitCode = 2;\n    return;\n  }\n  throw err;\n}","preventionTips":["Read --help to list required flags before scripting.","Set sensible defaults in flag definitions for commonly-supplied values.","Keep wrapper scripts in sync with required-flag changes across versions."],"tags":["cli","validation","required-flag"],"backgroundTag":"missing-required-flag","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}