affaan-m/ECC · error · Error

Unknown argument

Error message

Unknown argument: ${flag}

What it means

work-items.js assignOption maps a known flag to an option on the parsed object via a long if/else chain; if the flag matches none of the recognized options, the terminal else throws 'Unknown argument: <flag>'. This is the value-flag level allowlist check (separate from parseArgs' own unknown-flag branch).

Solutions

1. Use a flag supported by assignOption (see the chain: --session/--session-id, --source, --source-id, --status, --title, --url, etc.)
2. Check spelling and aliases — some flags have two accepted forms
3. Run with --help to list supported flags for the chosen command
4. If maintaining the script, add the missing `else if` branch for any flag added to VALUE_FLAGS

Example fix

// before
node scripts/work-items.js add --titel "Fix bug"
// after
node scripts/work-items.js add --title "Fix bug"

const KNOWN_FLAGS = new Set(['--session','--session-id','--source','--source-id','--status','--title','--url' /* plus others from assignOption */]);
const unknown = process.argv.slice(2).filter(a => a.startsWith('--') && !KNOWN_FLAGS.has(a) && a !== '--help' && a !== '--json');
if (unknown.length > 0) throw new Error(`Unknown argument(s): ${unknown.join(', ')}`);

function isKnownWorkItemsFlag(flag) {
  return VALUE_FLAGS.has(flag) || flag === '--help' || flag === '--json';
}

try {
  const options = parseArgs(process.argv);
} catch (err) {
  if (err.message.startsWith('Unknown argument:')) {
    console.error(`${err.message}. Run 'work-items --help' for the supported flags.`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: parseArgs forwards a flag listed in VALUE_FLAGS to assignOption that the chain doesn't handle (e.g. a newly added VALUE_FLAGS entry missed in assignOption), or in practice a caller passes an unsupported option like `--foo bar`.

Common situations: Flags remembered from other ECC scripts (--target, --action) used against work-items; docs drift where a flag was renamed (e.g. --session-id vs --session); editing the script and adding a flag to VALUE_FLAGS without adding the assignOption branch.

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

• Unknown argument
• Unknown argument
• decisions does not accept a session ID when --all is set
• Invalid value: expected a path
• must use non-empty key=value form

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/2d57b3e68a3af636. Report an issue: GitHub.

Appendix: source

Thrown at scripts/work-items.js:80

function assignOption(options, flag, value) {
  if (flag === '--as') options.claimAs = value;
  else if (flag === '--db') options.dbPath = value;
  else if (flag === '--github-repo') options.githubRepo = value;
  else if (flag === '--id') options.id = value;
  else if (flag === '--limit') options.limit = value;
  else if (flag === '--metadata-json') options.metadataJson = value;
  else if (flag === '--owner') options.owner = value;
  else if (flag === '--priority') options.priority = value;
  else if (flag === '--repo' && options.command === 'sync-github') options.githubRepo = value;
  else if (flag === '--repo' || flag === '--repo-root') options.repoRoot = value;
  else if (flag === '--session' || flag === '--session-id') options.sessionId = value;
  else if (flag === '--source') options.source = value;
  else if (flag === '--source-id') options.sourceId = value;
  else if (flag === '--status') options.status = value;
  else if (flag === '--title') options.title = value;
  else if (flag === '--url') options.url = value;
  else throw new Error(`Unknown argument: ${flag}`);
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const parsed = {
    command: 'list',
    dbPath: null,
    help: false,
    json: false,
    limit: 20,
    positionals: []
  };

  if (args[0] && !args[0].startsWith('-')) {
    parsed.command = args.shift();
  }

  for (let index = 0; index < args.length; index += 1) {

View on GitHub (pinned to 8321021c54)