{"record":{"id":"b9f5e1125cf50e3e","repo":"heygen-com/hyperframes","slug":"unknown-flag-bad","errorCode":null,"errorMessage":"Unknown flag: ${bad}","messagePattern":"Unknown flag: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/utils/reject-unknown-flags.ts","lineNumber":67,"sourceCode":"}\n\n/**\n * Throw on the first flag in `rawArgs` not declared by `cmd` (its args + aliases\n * + the global set). Only dash-prefixed tokens are inspected, so positionals and\n * flag values pass through untouched. Stops at `--`.\n */\nexport function assertKnownFlags(cmd: CommandDef<ArgsDef>, rawArgs: string[]): void {\n  if (!Array.isArray(rawArgs)) return;\n  // citty types `args` as Resolvable<ArgsDef> (it may be a fn/promise); every\n  // hyperframes command uses a static object, so treat anything else as \"no\n  // declared args\" and skip validation rather than risk a wrong rejection.\n  const rawDef = cmd.args;\n  const args = rawDef && typeof rawDef === \"object\" ? (rawDef as ArgsDef) : undefined;\n  const known = knownFlags(args);\n  for (const tok of rawArgs) {\n    if (tok === \"--\") break;\n    const bad = unknownFlagIn(tok, known);\n    if (bad) throw new Error(`Unknown flag: ${bad}`);\n  }\n}\n","sourceCodeStart":49,"sourceCodeEnd":70,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/utils/reject-unknown-flags.ts#L49-L70","documentation":"Thrown by assertKnownFlags when a CLI command receives a dash-prefixed flag token that is not declared in the command's args definition, its aliases, or the global ALWAYS_KNOWN set (help, h, version, v, json). This is a guard against citty's permissive default behavior of silently ignoring unrecognized flags, which would cause the flag value to be dropped and the command to fall back to its default — a silent wrong result.","triggerScenarios":"Typing a flag name that doesn't exist on the command (e.g. --out instead of --output, --quality instead of --quality-level), using a flag from a different command by mistake, or misspelling a flag. The validator checks both camelCase and kebab-case variants, so --gif-loop and --gifLoop are both accepted if the arg is declared.","commonSituations":"Using --out instead of --output/-o on the render command; using a flag that was renamed in a newer version; copying a command from documentation for a different tool; forgetting that some flags are command-specific (e.g. --port only applies to studio commands).","solutions":["Run the command with --help to see all valid flags and their aliases for that specific command.","Check for typos in the flag name — the error message shows exactly which flag was rejected (e.g. 'Unknown flag: --out').","Convert camelCase arg names to kebab-case on the command line (e.g. --gifLoop becomes --gif-loop).","Update the CLI in case the flag was renamed in a newer version."],"exampleFix":"// before: hyperframes render --out video.mp4\n// after:  hyperframes render --output video.mp4  (or -o video.mp4)","handlingStrategy":"validation","validationCode":"import { assertKnownFlags, type knownFlags } from \"./reject-unknown-flags.js\";\n\n// Pre-validate before the command runs (assertKnownFlags throws on first unknown)\n// This IS the validation — call it at the top of every command handler:\nassertKnownFlags(cmd, process.argv.slice(2));","typeGuard":null,"tryCatchPattern":"try {\n  assertKnownFlags(cmd, rawArgs);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"Unknown flag:\")) {\n    console.error(`${err.message}\\nRun with --help to see valid flags.`);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Always run with --help first when unsure about available flags.","Remember that camelCase arg names (gifLoop) are passed as --gif-loop on the CLI.","Check command-specific documentation — not all flags apply to all commands."],"tags":["cli","flags","validation","user-error"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}