nexu-io/open-design · error · Error

unknown flag: --${key}. Run with --help for the list of acce

Error message

unknown flag: --${key}. Run with --help for the list of accepted flags.

What it means

Thrown by parseFlags when an argv token starts with '--' but its key is not in the union of the command's declared string and boolean flags. parseFlags is the shared CLI flag parser used by every `od` subcommand; each subcommand declares its known flags and the parser rejects anything else to catch typos and stale docs.

Source

Thrown at apps/daemon/src/cli.ts:1745

  const stringFlags = opts.string instanceof Set ? opts.string : new Set();
  const booleanFlags = opts.boolean instanceof Set ? opts.boolean : new Set();
  const knownFlags = new Set([...stringFlags, ...booleanFlags]);
  // Positionals collected silently; callers that take `<id>` style
  // positional args (e.g. `od plugin info <id>`) re-scan `argv`
  // themselves to pick them up. Strict positional rejection here
  // would break those commands, so we only enforce strict-flag
  // semantics for things that *are* prefixed with `--`.
  const out = {};
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (!a || !a.startsWith('--')) {
      // Positional — let the caller decide what to do with it.
      continue;
    }
    const eq = a.indexOf('=');
    const key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
    if (knownFlags.size > 0 && !knownFlags.has(key)) {
      throw new Error(
        `unknown flag: --${key}. Run with --help for the list of accepted flags.`,
      );
    }
    if (eq >= 0) {
      out[key] = a.slice(eq + 1);
      continue;
    }
    if (booleanFlags.has(key)) {
      out[key] = true;
      continue;
    }
    if (stringFlags.has(key)) {
      const next = argv[i + 1];
      if (next == null) {
        throw new Error(`flag --${key} requires a value`);
      }
      out[key] = next;
      i++;

View on GitHub (pinned to 5be4028344)

Solutions

1. Run `od <subcommand> --help` and copy the exact flag name from the accepted list.
2. Check for typos — the message echoes the unknown key.
3. Confirm the flag exists in the version of the daemon you are running (CLI surface was extended across releases).
4. If the flag genuinely should exist, add it to the subcommand's boolean/string flag set in cli.ts.

Example fix

# before
od automation create --shedule hourly:30
# after
od automation create --schedule hourly:30

// before invoking od, check the flags you pass are in the subcommand's help
const { stdout } = await run(['od', subcommand, '--help']);
const known = parseKnownFlags(stdout);
for (const flag of passedFlags) {
  if (!known.has(flag)) throw new Error(`unknown flag: --${flag}`);
}

try { await runOd(args); }
catch (e) {
  if (String(e.message).startsWith('unknown flag:')) {
    // surface help to the user, suggest the closest known flag
    suggestFlag(e.message);
    return;
  }
  throw e;
}

When it happens

Trigger: Running an `od <subcommand>` with a flag that subcommand does not accept — e.g. `od automation create --shedule hourly:30` (typo), `od brand rebuild --force` (no such flag), or a flag meant for a different subcommand.

Common situations: Typos in flag names; using a flag from an older/newer version; copy-pasting a command from docs for a different subcommand; mixing long-form abbreviations that the parser does not support.

Related errors

• flag --${key} requires a value
• --schedule is required. Forms: hourly:<minute> | daily:HH:MM
• --schedule hourly requires :<minute>, 0-59
• --schedule ${kind} requires :HH:MM[:TZ]
• --schedule ${kind} time must be HH:MM (24h)

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/438600f654959328. Report an issue: GitHub.