Egonex-AI/Understand-Anything · error

Unknown option: ${arg}

Error message

Unknown option: ${arg}

What it means

Generic command-line validation guard in parseArgs, thrown as the fall-through branch when an argument does not match any recognized option ('--exclude') and is not consumed as a positional. It fires when the script `node prepare-incremental.mjs <projectRoot> <baseCommit>` is invoked with an unsupported flag — e.g. a typo like '--exlude' or an option the parser does not implement. The faulty input is the unrecognized argv element interpolated into the message. Valid usage is exactly two positionals plus optionally '--exclude <patterns>' with comma-separated patterns.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-incremental.mjs:463

      && !removedNodeIds.has(edge.target)
      && !(edge.type === 'imports' && refreshedImportSourceIds.has(edge.source))
      && retainedIds.has(edge.source)
      && retainedIds.has(edge.target),
  );
  return { nodes, edges };
}

function parseArgs(argv) {
  const positionals = [];
  const excludePatterns = [];
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--exclude') {
      const value = argv[++i];
      if (!value || value.startsWith('--')) throw new Error('--exclude requires patterns');
      excludePatterns.push(...value.split(',').map(item => item.trim()).filter(Boolean));
    } else if (arg.startsWith('--')) {
      throw new Error(`Unknown option: ${arg}`);
    } else {
      positionals.push(arg);
    }
  }
  if (positionals.length !== 2) {
    throw new Error(
      'Usage: node prepare-incremental.mjs <projectRoot> <baseCommit> [--exclude <patterns>]',
    );
  }
  return { projectRoot: positionals[0], baseCommit: positionals[1], excludePatterns };
}

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const projectRoot = realpathSync(args.projectRoot);
  const uaDir = resolveUaDir(projectRoot);
  const intermediateDir = join(uaDir, 'intermediate');
  mkdirSync(intermediateDir, { recursive: true });

View on GitHub (pinned to 07edf82a04)

Solutions

  1. Remove the unsupported flag; the script accepts only <projectRoot> <baseCommit> and --exclude <patterns>
  2. Fix typos, e.g. --exlude → --exclude
  3. Check the usage message: node prepare-incremental.mjs <projectRoot> <baseCommit> [--exclude <patterns>]
  4. If you need a new option, add it to parseArgs in prepare-incremental.mjs

Example fix

// before
node prepare-incremental.mjs . HEAD --exlude dist
// after
node prepare-incremental.mjs . HEAD --exclude dist
Defensive patterns

Strategy: validation

Validate before calling

const allowed = new Set(['--exclude']);
const bad = process.argv.slice(2).filter(a => a.startsWith('--') && !allowed.has(a));
if (bad.length) console.error(`Unsupported flags: ${bad.join(' ')}`);

Try / catch

try {
  const parsed = parseArgs(argv);
} catch (err) {
  if (err.message.startsWith('Unknown option')) {
    console.error(`${err.message}\nUsage: node prepare-incremental.mjs <projectRoot> <baseCommit> [--exclude <patterns>]`);
    process.exit(1);
  }
  throw err;
}

Prevention

When it happens

Trigger: Invoking prepare-incremental.mjs with an unsupported flag such as --verbose, --dry-run, a misspelled --exlude, or any option not implemented by the script.

Common situations: Copy-pasting flags from another script in the /understand skill, typos in flag names, or assuming options supported by the main skill are also supported by this helper script.

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 Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/dc7f3afbbd960e7c. Report an issue: GitHub.