Yeachan-Heo/oh-my-codex · error

Missing command to run. ${SPARKSHELL_USAGE}

Error message

Missing command to run.
${SPARKSHELL_USAGE}

What it means

After stripping wrapper-only options, no arguments remain — sparkshell has no command to execute. The usage text is included to show expected invocation shape.

Source

Thrown at src/cli/sparkshell.ts:303

      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) {
    throw new Error(`Missing command to run.\n${SPARKSHELL_USAGE}`);
  }

  if (args[0] === '--shell') {
    const script = args[1];
    if (!script) throw new Error(`--shell requires a command string.\n${SPARKSHELL_USAGE}`);
    if (args.length !== 2) throw new Error(`--shell does not accept additional arguments.\n${SPARKSHELL_USAGE}`);
    return { kind: 'command', argv: resolveFallbackShellArgv(script, options) };
  }
  if (args[0]?.startsWith('--shell=')) {
    const script = args[0].slice('--shell='.length);
    if (!script.trim()) throw new Error(`--shell requires a command string.\n${SPARKSHELL_USAGE}`);
    if (args.length !== 1) throw new Error(`--shell does not accept additional arguments.\n${SPARKSHELL_USAGE}`);
    return { kind: 'command', argv: resolveFallbackShellArgv(script, options) };
  }

  const paneStart = args.findIndex((arg) => arg === '--tmux-pane' || arg.startsWith('--tmux-pane='));
  if (paneStart < 0) {
    return { kind: 'command', argv: [...args] };

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Append the command to run after the flags, e.g. `omx sparkshell --json -- npm test`
2. Use `--` to separate wrapper flags from the command
3. If scripting, assert the command array is non-empty before invoking

Example fix

# before
omx sparkshell --json
# after
omx sparkshell --json -- npm test

if (args.filter((a) => a !== '--').length === 0) { throw new UsageError('sparkshell requires a command'); }

catch (e) { if (String(e).startsWith('Missing command to run')) { printUsage(); } else throw e; }

When it happens

Trigger: parseSparkShellFallbackInvocation called with args that are all wrapper flags (e.g. only `--json`) or an empty array.

Common situations: User runs `omx sparkshell` with no command, or passes only tuning flags forgetting the actual command; scripts with an empty command array variable.

Related errors

• ${token} requires a value. ${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/2f146323067c7ed2. Report an issue: GitHub.