Yeachan-Heo/oh-my-codex · error · Error

Unknown capabilities option: ${arg}

Error message

Unknown capabilities option: ${arg}

What it means

While parsing arguments for the `capabilities` command, an option starting with `--` was encountered that is not in the recognized option list (e.g. `--json`, `--observations`). Unrecognized long flags are rejected to catch typos early.

Source

Thrown at src/cli/capabilities.ts:110

      case "--json":
        parsed.json = true;
        break;
      case "--require-observations":
        parsed.requireObservations = true;
        break;
      case "--strict-external-schemas":
        parsed.strictExternalSchemas = true;
        break;
      case "--lockfile":
        parsed.lockfile = requireValue(args, index, arg);
        index += 1;
        break;
      case "--observations":
        parsed.observations = requireValue(args, index, arg);
        index += 1;
        break;
      default:
        if (arg.startsWith("--")) throw new Error(`Unknown capabilities option: ${arg}`);
        break;
    }
  }
  return parsed;
}

function requireValue(args: string[], index: number, flag: string): string {
  const value = args[index + 1];
  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
  return value;
}

function printResult(result: unknown, json: boolean): void {
  if (json) {
    console.log(JSON.stringify(result, null, 2));
    return;
  }
  const check = result as Partial<CapabilityCheckResult> & { lockfile?: string };

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Run with --help to see the supported options for the subcommand
2. Remove or correct the unsupported flag
3. Check for a renamed flag in the changelog if the option used to exist

Example fix

# before
omx capabilities list --format json

# after
omx capabilities list --json

const KNOWN_OPTS = new Set(['--json', '--observations']); // sync with parseCapabilitiesArgs
for (const a of args) {
  if (a.startsWith('--') && !KNOWN_OPTS.has(a)) {
    console.error(`Unsupported option: ${a}`);
    process.exit(1);
  }
}

try {
  await capabilitiesCommand(args);
} catch (e) {
  if ((e as Error).message.startsWith('Unknown capabilities option')) { /* warn and strip the flag */ }
  else throw e;
}

When it happens

Trigger: Passing any `--flag` not handled by the switch in `parseCapabilitiesArgs`, e.g. `omx capabilities list --verbose` or `--format`.

Common situations: Assuming generic flags like `--verbose`, `--quiet`, or `--format` exist; flags renamed between versions; copy-paste from other tools' syntax.

Related errors

• Unknown mission option: ${arg}
• --keep-policy must be one of: score_improvement, pass_only
• Unknown capabilities subcommand: ${parsed.subcommand}
• ${flag} requires a value
• Unknown hooks subcommand: ${subcommand}

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/31e49699176e4edd. Report an issue: GitHub.