affaan-m/ECC · error · Error

Expected at most one agents directory argument

Error message

Expected at most one agents directory argument

What it means

parseArgs throws when more than one positional argument is supplied; the tool accepts at most a single agents directory path. Extra positionals indicate a malformed invocation (unquoted paths with spaces often cause this).

Solutions

1. Quote the directory path if it contains spaces: node scripts/gemini-adapt-agents.js "/path with spaces".
2. Pass only one agents directory per run.
3. Omit the argument to use the default .gemini/agents.

Example fix

// before
$ node scripts/gemini-adapt-agents.js agents1 agents2
Error: Expected at most one agents directory argument
// after
$ node scripts/gemini-adapt-agents.js agents1

const positionals = process.argv.slice(2).filter(a => !a.startsWith('-'));
if (positionals.length > 1) {
  console.error('Pass at most one agents directory');
  process.exit(1);
}

try {
  adaptAgents(process.argv.slice(2));
} catch (err) {
  if (/at most one agents directory/.test(err.message)) {
    console.error('Usage: gemini-adapt-agents.js [agentsDir]');
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Running `node scripts/gemini-adapt-agents.js dirA dirB`, or accidentally passing extra unquoted paths / stray words that don't start with '-' so they count as positionals.

Common situations: Quoting mistakes turning one path into two arguments, copy-pasting a command with multiple source dirs from docs, or forgetting a flag so its would-be value becomes a second positional.

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
• Agents directory not found
• --all-harnesses and --harness are mutually exclusive.
• all overlays must be readable local files

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

Appendix: source

Thrown at scripts/gemini-adapt-agents.js:38

  return [
    'Adapt ECC agent frontmatter for Gemini CLI.',
    '',
    'Usage:',
    '  node scripts/gemini-adapt-agents.js [agents-dir]',
    '',
    'Defaults to .gemini/agents under the current working directory.',
    'Rewrites tools: to Gemini-compatible tool names and removes unsupported color: metadata.'
  ].join('\n');
}

function parseArgs(argv) {
  if (argv.includes('--help') || argv.includes('-h')) {
    return { help: true };
  }

  const positional = argv.filter(arg => !arg.startsWith('-'));
  if (positional.length > 1) {
    throw new Error('Expected at most one agents directory argument');
  }

  return {
    help: false,
    agentsDir: path.resolve(positional[0] || path.join(process.cwd(), '.gemini', 'agents')),
  };
}

function ensureDirectory(dirPath) {
  if (!fs.existsSync(dirPath)) {
    throw new Error(`Agents directory not found: ${dirPath}`);
  }

  if (!fs.statSync(dirPath).isDirectory()) {
    throw new Error(`Expected a directory: ${dirPath}`);
  }
}

View on GitHub (pinned to 8321021c54)