heygen-com/hyperframes · error · Error

Use either --all or --capability, not both

Error message

Use either --all or --capability, not both

What it means

Thrown by runCapabilityQuery when both --all and --capability <id> are provided. --all prints the entire exhaustive catalog; --capability narrows to one family/item. They are mutually exclusive output scopes and cannot be combined.

Source

Thrown at packages/cli/src/commands/media-treatment.ts:564

  analyze?: boolean;
  clear?: boolean;
  "dry-run"?: boolean;
  json?: boolean;
}

function runCapabilityQuery(args: MediaTreatmentCommandArgs): void {
  const capability = readOptionalString(args.capability);
  const hasMutationOption = [
    readOptionalString(args.selector),
    readOptionalString(args.grading),
    args.clear,
    args["dry-run"],
    args.apply,
    args.analyze,
  ].some(Boolean);
  if (hasMutationOption) throw new Error("--capabilities cannot be combined with mutation options");
  if (args.all === true && capability)
    throw new Error("Use either --all or --capability, not both");

  let capabilities: unknown = getMediaTreatmentCapabilityOverview();
  if (args.all === true) capabilities = getHfColorGradingCapabilities();
  else if (capability) capabilities = getMediaTreatmentCapabilityDetail(capability);
  console.log(JSON.stringify(withMeta({ ok: true, capabilities }), null, 2));
}

function resolveMutationFile(args: MediaTreatmentCommandArgs) {
  const project = resolveProject(readOptionalString(args.project));
  const fileArg = readOptionalString(args.file) ?? "index.html";
  const filePath = resolve(project.dir, fileArg);
  if (!isPathInside(filePath, project.dir) || !filePath.toLowerCase().endsWith(".html")) {
    throw new Error("--file must be an HTML file inside the project");
  }
  if (!existsSync(filePath)) throw new Error(`Composition file not found: ${fileArg}`);
  return { project, filePath };
}

View on GitHub (pinned to c2996c8626)

Solutions

1. For the full catalog: use `--capabilities --all` alone
2. For one capability: use `--capabilities --capability <id>` alone
3. For a concise overview: use `--capabilities` alone

Example fix

// before
hyperframes media-treatment --capabilities --all --capability wheels
// after — choose one scope
hyperframes media-treatment --capabilities --all
// or
hyperframes media-treatment --capabilities --capability wheels

function assertExclusiveScope(all?: boolean, capability?: string): void {
  if (all && capability) {
    throw new Error('Use --all or --capability, not both');
  }
}

When it happens

Trigger: Running `hyperframes media-treatment --capabilities --all --capability wheels` or `--all --capability kuwahara`.

Common situations: Agent loops that pass --all for completeness then append --capability for focus. Users exploring who set both flags expecting a filtered subset of --all.

Related errors

• Use either --apply with --grading or --clear, not both
• --capabilities cannot be combined with mutation options
• --analyze cannot be combined with mutation options
• --selector-index must be a non-negative integer
• Media analysis requires a local project asset; freeze remote

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