--shell does not accept additional arguments. ${SPARKSHELL_U

Error message

--shell does not accept additional arguments.
${SPARKSHELL_USAGE}

What it means

`--shell <script>` was given but additional arguments followed; the shell form accepts exactly one command string and no extra positional args. Usage text is appended.

Source

Thrown at src/cli/sparkshell.ts:309

    }
    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

Remove the extra arguments, keeping only `--shell <script>`
If you meant to run a bare command with args, drop `--shell` and pass them positionally: `omx sparkshell -- npm test --watch`
Quote the whole script so args meant for the inner shell travel inside the string

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

const i = args.indexOf('--shell');
const ok = i === -1 || args.length === i + 2; // script must be the last token

Try / catch

catch (e) { if (String(e).startsWith('--shell does not accept')) { printUsage(); } else throw e; }

Prevention

Put all inner-command args inside the quoted script string
Don't append flags after the --shell script token

When it happens

Trigger: `omx sparkshell --shell "echo hi" extra-arg` — args.length !== 2 after stripping wrapper options.

Common situations: User mixes the one-shot --shell form with positional command args intended for the default form; leftover flags after the script string.

Related errors

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