jackwener/OpenCLI · error · ArgumentError

--model requires a canonical model id (e.g. "2.5-flash"). Us

Error message

--model requires a canonical model id (e.g. "2.5-flash"). Use "opencli gemini models" to list available values.

What it means

validateAskModelValue in clis/gemini/ask.js throws this ArgumentError when `--model` is omitted, empty, or falsy. The gemini ask command requires a canonical model id such as `2.5-flash`; it will not guess or default. The message points to `opencli gemini models` for the list of valid values.

Source

Thrown at clis/gemini/ask.js:51

    return value;
}

function requireDiscoveredModels(value) {
    const unwrapped = unwrapBrowserBridgeEnvelope(value);
    if (!Array.isArray(unwrapped)) {
        throw new CommandExecutionError('Gemini model discovery returned a malformed result');
    }
    for (const row of unwrapped) {
        if (!row || typeof row.model !== 'string' || !Array.isArray(row.thinkingValues)) {
            throw new CommandExecutionError('Gemini model discovery returned a malformed row');
        }
    }
    return unwrapped;
}

function validateAskModelValue(value) {
    if (!value) {
        throw new ArgumentError(
            '--model requires a canonical model id (e.g. "2.5-flash"). ' +
            'Use "opencli gemini models" to list available values.'
        );
    }
    // Reject short aliases like "pro", "flash", "flash-lite" that lack a version number.
    if (!/\d+\.\d+/.test(value)) {
        throw new ArgumentError(
            '--model "' + value + '" is not accepted. ' +
            'Short aliases like "pro", "flash", or "flash-lite" are not supported. ' +
            'Use a canonical model id (e.g. "2.5-flash"). ' +
            'Use "opencli gemini models" to list available values.'
        );
    }
    // Must match canonical format: X.Y-variant
    if (!/^\d+\.\d+-[a-z][a-z-]*$/.test(value)) {
        throw new ArgumentError(
            '--model "' + value + '" is not a valid canonical model id. ' +
            'Expected format: version-variant (e.g. "2.5-flash", "3.1-pro"). ' +

View on GitHub (pinned to 49907e53dc)

Solutions

1. Add an explicit canonical model id: `opencli gemini ask --model 2.5-flash ...`
2. Run `opencli gemini models` to see valid canonical ids, then pick one
3. Fix the empty variable in your wrapper script (e.g. check `${MODEL_ID:?unset}` before invoking)

Example fix

// before
opencli gemini ask --prompt "hello"
// after
opencli gemini ask --model 2.5-flash --prompt "hello"

if (!process.argv.includes('--model')) {
  console.error('gemini ask requires --model <version-variant>, e.g. --model 2.5-flash');
  process.exit(2);
}

function hasModelArg(args) {
  return typeof args.model === 'string' && args.model.trim().length > 0;
}

try {
  await geminiAsk(args);
} catch (err) {
  if (err.name === 'ArgumentError' && err.message.includes('requires a canonical model id')) {
    console.error('Usage: opencli gemini ask --model 2.5-flash --prompt "..."');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running `opencli gemini ask --prompt "..."` without `--model`, or with `--model ""` / `--model` followed by no value.

Common situations: Copy-pasting an example command that omitted the flag; assuming a default model exists; a script variable holding the model id being empty due to unset config/env value.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --model "${value}" is not accepted. Short aliases like "pro"
• --model "${value}" is not a valid canonical model id. Expect
• --thinking must be 'standard' or 'extended', got '${thinking
• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/be50dffde938293b. Report an issue: GitHub.