What causes "--tail-lines requires a numeric value. ${SPARKSHELL_USAGE}" in Yeachan-Heo/oh-my-codex?

Add an integer 100-1000 after --tail-lines: `--tail-lines 400`

--tail-lines requires a numeric value. ${SPARKSHELL_USAGE}

Error message

--tail-lines requires a numeric value.
${SPARKSHELL_USAGE}

What it means

In tmux-pane mode, --tail-lines was given without a numeric value: it was the last token or the next token started with '-' (which includes negative numbers).

Source

Thrown at src/cli/sparkshell.ts:345

  for (let index = 0; index < args.length; index += 1) {
    const token = args[index];
    if (token === '--tmux-pane') {
      const next = args[index + 1];
      if (!next || next.startsWith('-')) throw new Error(`--tmux-pane requires a pane id.\n${SPARKSHELL_USAGE}`);
      paneId = next;
      index += 1;
      continue;
    }
    if (token.startsWith('--tmux-pane=')) {
      const value = token.slice('--tmux-pane='.length).trim();
      if (!value) throw new Error(`--tmux-pane requires a pane id.\n${SPARKSHELL_USAGE}`);
      paneId = value;
      continue;
    }
    if (token === '--tail-lines') {
      const next = args[index + 1];
      if (!next || next.startsWith('-')) throw new Error(`--tail-lines requires a numeric value.\n${SPARKSHELL_USAGE}`);
      const parsed = Number.parseInt(next, 10);
      if (!Number.isFinite(parsed) || parsed < 100 || parsed > 1000) {
        throw new Error(`--tail-lines must be an integer between 100 and 1000.\n${SPARKSHELL_USAGE}`);
      }
      tailLines = parsed;
      sawTailLines = true;
      index += 1;
      continue;
    }
    if (token.startsWith('--tail-lines=')) {
      const parsed = Number.parseInt(token.slice('--tail-lines='.length), 10);
      if (!Number.isFinite(parsed) || parsed < 100 || parsed > 1000) {
        throw new Error(`--tail-lines must be an integer between 100 and 1000.\n${SPARKSHELL_USAGE}`);
      }
      tailLines = parsed;
      sawTailLines = true;
      continue;
    }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Add an integer 100-1000 after --tail-lines: `--tail-lines 400`
Use the equals form: `--tail-lines=400`

Example fix

# before
sparkshell --tmux-pane 0 --tail-lines
# after
sparkshell --tmux-pane 0 --tail-lines 400

Defensive patterns

Strategy: validation

Validate before calling

const args = ['--tmux-pane', paneId];
if (tailLines !== undefined) {
  if (!Number.isInteger(tailLines) || tailLines < 100 || tailLines > 1000) throw new RangeError('tailLines must be 100-1000');
  args.push('--tail-lines', String(tailLines));
}

Prevention

Validate the integer range before building the command
Omit --tail-lines to accept the 200 default

When it happens

Trigger: `sparkshell --tmux-pane 0 --tail-lines` (trailing flag) or `--tail-lines --verbose` (next token is an option).

Common situations: Truncated command lines from scripts, flag ordering mistakes, attempting a negative value.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

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