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

unknown list option: ${unknown[0]}

Error message

unknown list option: ${unknown[0]}

What it means

The `list` subcommand accepts only the --json flag (and no arguments). Any other token in argv is rejected with `unknown list option: <token>` before the catalog manifest is read.

Source

Thrown at src/cli/list.ts:37

  console.log(
    `Skills: ${contract.counts.skillCount} (${contract.counts.activeSkillCount} active)`,
  );
  for (const skill of contract.skills) console.log(formatEntry(skill));
  console.log(
    `Agents: ${contract.counts.promptCount} (${contract.counts.activeAgentCount} active)`,
  );
  for (const agent of contract.agents) console.log(formatEntry(agent));
}

export async function listCommand(args: string[]): Promise<void> {
  if (args.includes("--help") || args.includes("-h")) {
    console.log(LIST_USAGE);
    return;
  }

  const unknown = args.filter((arg) => arg !== "--json");
  if (unknown.length > 0) {
    throw new Error(`unknown list option: ${unknown[0]}`);
  }

  const manifest = readCatalogManifest();
  const contract = toPublicCatalogContract(manifest);

  if (args.includes("--json")) {
    console.log(JSON.stringify(contract));
    return;
  }

  printHumanList(contract);
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Remove the unsupported flag/argument and re-run with just `list` or `list --json`
2. Check LIST_USAGE (printed with no args or help) for the supported surface
3. If filtering is needed, pipe JSON output through jq instead of CLI flags
4. Pin scripts to a version whose interface matches your expectations

Example fix

# before
mycli list --all

# after
mycli list --json | jq '.[] | select(.active)'

const args = process.argv.slice(2);
const unknown = args.filter((a) => a !== "--json");
if (unknown.length > 0) {
  console.error(`Unsupported list option: ${unknown[0]}`);
  process.exit(2);
}
await listCommand(args);

function isValidListArgs(args: readonly string[]): boolean {
  return args.every((a) => a === "--json");
}

try { await listCommand(args); }
catch (e) { if (/unknown list option/.test(String(e))) { console.error('Usage: list [--json]'); process.exit(2); } throw e; }

When it happens

Trigger: Running listCommand with anything besides an empty array or ['--json'], e.g. `list --all`, `list foo`, `list --json --verbose`, or a positional argument.

Common situations: Copy-pasting flags from another CLI version or different subcommand; shell aliases appending flags; scripts written against an older/newer interface; assuming a --help or filter flag exists.

Related errors

• Unknown argument: ${token}
• Unknown MCP target: ${firstArg} ${MCP_SERVE_USAGE}
• Usage: omx team [N:agent-type] "<task description>"
• Usage: omx team status <team-name> [--json]
• Usage: omx team await <team-name> [--timeout-ms <ms>] [--aft

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