What causes "unknown argument: ${arg}" in Hmbown/CodeWhale?

Run with --help to list the accepted arguments and use exactly those.

unknown argument

Error message

unknown argument: ${arg}

What it means

CLI parsing guard in parseArgs(): the validator was invoked with an argument not in its known set (--runtime-env, --workspace-root, --check-filesystem, --json, -h/--help). It fails fast on typos and unsupported flags rather than silently ignoring them, so config validation never runs against misunderstood options.

Solutions

Run with --help to list the accepted arguments and use exactly those.
Fix the typo in the flag name (e.g. --env vs --envv).
Remove unexpected positional arguments; the validator takes flags only (env/app config come from the environment and config file).

Example fix

// before
node scripts/validate-config.mjs --env-file .env
// after
node scripts/validate-config.mjs --env .env   # or check --help for exact flag

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN = ['--help', '-h', '--env', '--json'];
const unknown = process.argv.slice(2).filter(a => a.startsWith('-') && !KNOWN.includes(a));
if (unknown.length) { console.error('unknown:', unknown); process.exit(1); }

Type guard

function isKnownFlag(arg) {
  return ['-h', '--help', '--env', '--json'].includes(arg);
}

Try / catch

try {
  const args = parseArgs(process.argv.slice(2));
} catch (e) {
  if (String(e.message).startsWith('unknown argument')) {
    printHelp();
    process.exit(2);
  }
  throw e;
}

Prevention

Run --help first when using the validator in new shells or CI scripts.
Keep flag names for the validator and the runtime bridge in a shared constant.
Add a lint/CI step that invokes the validator with its documented flags only.

When it happens

Trigger: Running `node integrations/feishu-bridge/scripts/validate-config.mjs` with a flag it does not recognize — misspellings like --envv, unsupported long options, or extra positional words.

Common situations: Copy-pasting flags from another script's docs; typo'd flag names; assuming the validator accepts the same flags as the bridge runtime itself.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/10ad2a055358de03. Report an issue: GitHub.

Appendix: source

Thrown at integrations/feishu-bridge/scripts/validate-config.mjs:72

      case "--runtime-env":
        parsed.runtimeEnv = argv[++index];
        break;
      case "--workspace-root":
        parsed.workspaceRoot = argv[++index];
        break;
      case "--check-filesystem":
        parsed.checkFilesystem = true;
        break;
      case "--json":
        parsed.json = true;
        break;
      case "-h":
      case "--help":
        printHelp();
        process.exit(0);
        break;
      default:
        throw new Error(`unknown argument: ${arg}`);
    }
  }
  return parsed;
}

async function appendFilesystemChecks(result, env, args) {
  const workspace = cleanEnvValue(env.CODEWHALE_WORKSPACE ?? env.DEEPSEEK_WORKSPACE);
  if (workspace) {
    await checkReadableDirectory(result, workspace, "workspace");
  }

  const threadMapPath = cleanEnvValue(env.FEISHU_THREAD_MAP_PATH);
  if (threadMapPath) {
    const parent = path.dirname(threadMapPath);
    await checkWritableDirectory(result, parent, "thread map directory");
  }

  if (args.env) {

View on GitHub (pinned to 433685b202)