Yeachan-Heo/oh-my-codex · error

--shell requires a command string.

Error message

--shell requires a command string.
${SPARKSHELL_USAGE}

What it means

`--shell` was passed as its own token but the next argument (the command string) is missing, so there is nothing to execute in the shell. Usage text is appended.

Solutions

1. Provide the script: `--shell "npm test"`
2. Or use the `=` form: `--shell="npm test"` which fails separately if the value is blank
3. Check shell quoting when the script itself contains quotes

Example fix

# before
omx sparkshell --shell
# after
omx sparkshell --shell "npm test"

const i = args.indexOf('--shell');
const ok = i === -1 || (i + 1 < args.length && args[i + 1].trim().length > 0);

catch (e) { if (String(e).startsWith('--shell requires a command string')) { printUsage(); } else throw e; }

When it happens

Trigger: `omx sparkshell --shell` as the last args, or `--shell` followed by nothing before end of args.

Common situations: Truncated command line, quoting mistakes that swallow the script argument, or dynamic arg construction dropping the script value.

Related errors

• --shell does not accept additional arguments.
• Missing command to run.
• requires a value.
• agents-init accepts at most one path argument.\n
• IMAGEGEN_CONTINUATION_USAGE

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

Appendix: source

Thrown at src/cli/sparkshell.ts:308

      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] };
  }

  let paneId: string | undefined;
  let tailLines = 200;
  let sawTailLines = false;

View on GitHub (pinned to 3ad79a8a6f)