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

Unknown capabilities subcommand: ${parsed.subcommand}

Error message

Unknown capabilities subcommand: ${parsed.subcommand}

What it means

The `capabilities` CLI command only accepts a fixed set of subcommands, and the first positional argument did not match any of them. The switch over `parsed.subcommand` fell through to the default branch and threw.

Source

Thrown at src/cli/capabilities.ts:73

        })),
      };
      printResult(result, parsed.json);
      return;
    }
    case "check": {
      const result = await checkCapabilitiesPreflight({
        cwd,
        lockfilePath: lockfile,
        observationsPath: parsed.observations,
        requireObservations: parsed.requireObservations,
        strictExternalSchemas: parsed.strictExternalSchemas,
      });
      printResult(result, parsed.json);
      if (!result.ok) process.exitCode = 1;
      return;
    }
    default:
      throw new Error(`Unknown capabilities subcommand: ${parsed.subcommand}`);
  }
}

function parseCapabilitiesArgs(args: string[]): ParsedCapabilitiesArgs {
  const parsed: ParsedCapabilitiesArgs = {
    subcommand: args[0],
    requireObservations: false,
    strictExternalSchemas: false,
    json: false,
    help: false,
  };
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    switch (arg) {
      case "--help":
      case "-h":
        parsed.help = true;
        break;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Run `omx capabilities --help` to list valid subcommands
2. Fix the typo in the subcommand name
3. Upgrade the CLI if the docs reference a subcommand your version lacks

Example fix

# before
omx capabilities lst

# after
omx capabilities list

const KNOWN = new Set(['list', 'get', 'check']); // sync with switch cases in capabilities.ts
const sub = args[0];
if (!sub || !KNOWN.has(sub)) {
  console.error(`Unknown capabilities subcommand. Valid: ${[...KNOWN].join(', ')}`);
  process.exit(1);
}

function isCapabilitiesSubcommand(s: string | undefined): s is 'list' | 'get' | 'check' {
  return !!s && ['list', 'get', 'check'].includes(s);
}

try {
  await capabilitiesCommand(args);
} catch (e) {
  if ((e as Error).message.startsWith('Unknown capabilities subcommand')) { /* show help */ }
  else throw e;
}

When it happens

Trigger: Running `omx capabilities <unknown>` where the first arg is not one of the supported subcommands (e.g. `list`, `get`, `check` per the switch), including misspellings or empty/undefined subcommand in some shells.

Common situations: Typos in subcommand names, using a subcommand from a different/newer version, or copy-pasting commands from outdated documentation.

Related errors

• --keep-policy must be one of: score_improvement, pass_only
• Unknown capabilities option: ${arg}
• ${flag} requires a value
• Unknown hooks subcommand: ${subcommand}
• Conflicting setup AGENTS merge policy flags: ${source} confl

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