heygen-com/hyperframes · error · Error

--for <path> is required

Error message

--for <path> is required

What it means

Thrown by parseGradeCompareArgs when `--for` is absent or empty. `--for` is the reference frame (image or video) onto which every candidate grade is rendered, so without it the command has nothing to compare against. readOptionalString returns undefined for missing/empty values, which trips the guard.

Source

Thrown at packages/cli/src/commands/grade-compare.ts:269

// The ungraded frame as a leading reference cell. An empty grading object
// normalizes to inactive, so the runtime renders the source image untouched —
// giving the agent a baseline to judge every candidate look against.
export function prependBaselineCell(cells: GradeCompareCell[]): GradeCompareCell[] {
  return [validateCell("original", {}), ...cells];
}

export function parseGradeCompareArgs(args: {
  for?: unknown;
  grades?: unknown;
  luts?: unknown;
  project?: unknown;
  out?: unknown;
  json?: unknown;
  timeout?: unknown;
}): ParsedGradeCompareArgs {
  const frameArg = readOptionalString(args.for);
  if (!frameArg) throw new Error("--for <path> is required");

  const gradesArg = readOptionalString(args.grades);
  const lutsArg = readOptionalString(args.luts);
  if (Boolean(gradesArg) === Boolean(lutsArg)) {
    throw new Error("Exactly one of --grades or --luts is required");
  }

  const projectDir = resolve(readOptionalString(args.project) ?? process.cwd());
  const framePath = resolveFromBase(projectDir, frameArg);
  const outPath = resolveFromBase(projectDir, readOptionalString(args.out) ?? "grade-compare.png");

  return {
    framePath,
    projectDir,
    outPath,
    source: gradesArg
      ? { kind: "grades", path: resolveFromBase(projectDir, gradesArg) }
      : { kind: "luts", value: lutsArg ?? "" },

View on GitHub (pinned to c2996c8626)

Solutions

1. Add `--for <path>` pointing at an image (.png/.jpg) or video (.mp4/.mov/etc.) file.
2. If the path is relative, remember it resolves against `--project` (default cwd) — verify the file exists there.
3. For programmatic callers, pass a non-empty `for` string to parseGradeCompareArgs.

Example fix

# before
hyperframes grade-compare --grades grades.json
# after
hyperframes grade-compare --for frame.png --grades grades.json

// Before calling parseGradeCompareArgs programmatically
if (!args.for || String(args.for).trim() === "") {
  throw new Error("--for <path> is required");
}
const parsed = parseGradeCompareArgs(args);

function hasForArg(args: { for?: unknown }): args is { for: string } {
  return typeof args.for === "string" && args.for.trim() !== "";
}

try {
  const parsed = parseGradeCompareArgs({ for: args.for, /* ... */ });
} catch (err) {
  if (/--for/.test((err as Error).message)) console.error("Missing --for; pass a reference frame path.");
  throw err;
}

When it happens

Trigger: Invoking `hyperframes grade-compare` without `--for`, or with `--for ""`. Also triggered programmatically by calling parseGradeCompareArgs({}) or parseGradeCompareArgs({ for: "" }).

Common situations: Forgetting the flag (note: citty's own `required: true` should catch the CLI path, but programmatic callers and some argument forms bypass it); passing an unset shell variable `$FRAME` that expands to empty.

Related errors

• Grade entry "${label}" must include a grading value
• --luts must include at least one LUT path
• Exactly one of --grades or --luts is required
• At least one grade cell is required
• Reference frame not found: ${framePath}

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