Yeachan-Heo/oh-my-codex · error

${token} requires a value. ${SPARKSHELL_USAGE}

Error message

${token} requires a value.
${SPARKSHELL_USAGE}

What it means

Argument parsing for the sparkshell wrapper: an option that requires a value (--budget, --cache-ttl-ms, --team, --worker) appears as the last token with no following value. The usage text is appended.

Source

Thrown at src/cli/sparkshell.ts:284

  } = options;

  if (platform !== 'win32') return ['sh', '-lc', script];
  if (commandExists('pwsh')) return ['pwsh', '-NoLogo', '-NoProfile', '-Command', script];
  if (commandExists('powershell.exe')) return ['powershell.exe', '-NoLogo', '-NoProfile', '-Command', script];
  return [env.ComSpec?.trim() || 'cmd.exe', '/d', '/s', '/c', script];
}

function stripSparkShellWrapperOptions(args: readonly string[]): string[] {
  let index = 0;
  while (index < args.length) {
    const token = args[index]!;
    if (token === '--') return [...args.slice(index + 1)];
    if (token === '--json' || token === '--since-last' || token.startsWith('--cache=')) {
      index += 1;
      continue;
    }
    if (token === '--budget' || token === '--cache-ttl-ms' || token === '--team' || token === '--worker') {
      if (args[index + 1] === undefined) throw new Error(`${token} requires a value.\n${SPARKSHELL_USAGE}`);
      index += 2;
      continue;
    }
    if (token.startsWith('--budget=') || token.startsWith('--cache-ttl-ms=') || token.startsWith('--team=') || token.startsWith('--worker=')) {
      index += 1;
      continue;
    }
    return [...args.slice(index)];
  }
  return [];
}

export function parseSparkShellFallbackInvocation(
  args: readonly string[],
  options: ParseSparkShellFallbackOptions = {},
): SparkShellFallbackInvocation {
  args = stripSparkShellWrapperOptions(args);
  if (args.length === 0) {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Supply the missing value: `--team myteam` (or `--team=myteam`)
2. Prefer the `=` form (--budget=100) to make value/flag pairing unambiguous
3. Re-check the usage string printed in the error for supported options

Example fix

# before
omx sparkshell --team -- npm test
# after
omx sparkshell --team core -- npm test

const VALUE_FLAGS = new Set(['--budget', '--cache-ttl-ms', '--team', '--worker']);
function argsWellFormed(args: string[]): boolean {
  for (let i = 0; i < args.length; i++) {
    if (VALUE_FLAGS.has(args[i]) && args[i + 1] === undefined) return false;
  }
  return true;
}

catch (e) { if (String(e).includes('requires a value')) { printUsage(); exit(2); } }

When it happens

Trigger: Invoking sparkshell with e.g. `--team` at the end of args, or `--budget` followed by another flag position that was already consumed as separate tokens where the value token is undefined.

Common situations: CLI typo, scripting that builds args dynamically and drops a value, or copy-pasting a command with a truncated tail.

Related errors

• Missing command to run. ${SPARKSHELL_USAGE}
• Unknown adapt argument: ${arg}
• Unknown adapt subcommand: ${subcommand}. Supported subcomman
• agents-init accepts at most one path argument.\n${AGENTS_INI
• --shell requires a command string. ${SPARKSHELL_USAGE}

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/20cdc6b08446c007. Report an issue: GitHub.