Yeachan-Heo/oh-my-codex · error

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

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.

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)

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. ${SPARKSHELL_U
• ${token} requires a value. ${SPARKSHELL_USAGE}
• Missing command to run. ${SPARKSHELL_USAGE}
• Unknown adapt argument: ${arg}
• Unknown adapt target: ${target}. Supported targets: ${suppor

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