heygen-com/hyperframes · error

Unknown flag: ${bad}

Error message

Unknown flag: ${bad}

What it means

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.

Source

Thrown at packages/cli/src/utils/reject-unknown-flags.ts:67

}

/**
 * Throw on the first flag in `rawArgs` not declared by `cmd` (its args + aliases
 * + the global set). Only dash-prefixed tokens are inspected, so positionals and
 * flag values pass through untouched. Stops at `--`.
 */
export function assertKnownFlags(cmd: CommandDef<ArgsDef>, rawArgs: string[]): void {
  if (!Array.isArray(rawArgs)) return;
  // citty types `args` as Resolvable<ArgsDef> (it may be a fn/promise); every
  // hyperframes command uses a static object, so treat anything else as "no
  // declared args" and skip validation rather than risk a wrong rejection.
  const rawDef = cmd.args;
  const args = rawDef && typeof rawDef === "object" ? (rawDef as ArgsDef) : undefined;
  const known = knownFlags(args);
  for (const tok of rawArgs) {
    if (tok === "--") break;
    const bad = unknownFlagIn(tok, known);
    if (bad) throw new Error(`Unknown flag: ${bad}`);
  }
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Run the command with --help to see all valid flags and their aliases for that specific command.
2. Check for typos in the flag name — the error message shows exactly which flag was rejected (e.g. 'Unknown flag: --out').
3. Convert camelCase arg names to kebab-case on the command line (e.g. --gifLoop becomes --gif-loop).
4. Update the CLI in case the flag was renamed in a newer version.

Example fix

// before: hyperframes render --out video.mp4
// after:  hyperframes render --output video.mp4  (or -o video.mp4)

import { assertKnownFlags, type knownFlags } from "./reject-unknown-flags.js";

// Pre-validate before the command runs (assertKnownFlags throws on first unknown)
// This IS the validation — call it at the top of every command handler:
assertKnownFlags(cmd, process.argv.slice(2));

try {
  assertKnownFlags(cmd, rawArgs);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Unknown flag:")) {
    console.error(`${err.message}\nRun with --help to see valid flags.`);
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• invalid-vars
• ${source}: ${errorMessage(error)}
• --batch must be a JSON array of objects, or an object with a
• ${source} contains zero rows.
• Row ${index} must be a JSON object of variable values.

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/b9f5e1125cf50e3e. Report an issue: GitHub.