headroomlabs-ai/headroom · error · ValueError

HEADROOM_LEARN_CLI={cli_override!r} is not a supported CLI.

Error message

HEADROOM_LEARN_CLI={cli_override!r} is not a supported CLI. Valid values: {valid}

What it means

Raised during LLM-backend resolution in headroom learn: after no API-key env vars (ANTHROPIC_API_KEY/OPENAI_API_KEY/GEMINI_API_KEY per _MODEL_DEFAULTS) matched, the explicit HEADROOM_LEARN_CLI override was read but its value does not match any name in _CLI_BACKENDS (claude, gemini, codex and friends). ValueError with the valid list so the misconfiguration is immediately visible.

Source

Thrown at headroom/learn/analyzer.py:138

      1. API key present → use corresponding LiteLLM model
      2. HEADROOM_LEARN_CLI env var → use specified CLI backend
      3. Auto-detect installed CLI tools (claude > gemini > codex)
      4. Raise RuntimeError with setup instructions
    """
    # 1. API key detection (existing behavior)
    for env_var, model in _MODEL_DEFAULTS:
        if os.environ.get(env_var):
            return model

    # 2. Explicit CLI selection via environment variable
    cli_override = os.environ.get("HEADROOM_LEARN_CLI")
    if cli_override:
        for cli_name, model, _cmd in _CLI_BACKENDS:
            if cli_name == cli_override:
                logger.info("HEADROOM_LEARN_CLI=%s — using %s CLI backend", cli_override, cli_name)
                return model
        valid = ", ".join(name for name, _, _ in _CLI_BACKENDS)
        raise ValueError(
            f"HEADROOM_LEARN_CLI={cli_override!r} is not a supported CLI. Valid values: {valid}"
        )

    # 3. Auto-detect installed CLI tools
    for cli_name, model, _cmd in _CLI_BACKENDS:
        if shutil.which(cli_name):
            logger.info("No API key found — auto-detected %s CLI as LLM backend", cli_name)
            return model

    raise RuntimeError(
        "No LLM API key found. headroom learn needs one of:\n"
        "  export ANTHROPIC_API_KEY=sk-ant-...   → uses claude-sonnet-4-6\n"
        "  export OPENAI_API_KEY=sk-...          → uses gpt-4o\n"
        "  export GEMINI_API_KEY=...             → uses gemini-flash-latest\n"
        "Or set HEADROOM_LEARN_CLI to a coding agent CLI (claude, gemini, codex).\n"
        "Or install one of those CLIs for auto-detection.\n"
        "Or specify a model directly: headroom learn --model <litellm-model-name>"
    )

View on GitHub (pinned to 322425c43b)

Solutions

Set a valid value: export HEADROOM_LEARN_CLI=claude (or gemini / codex — exactly as listed in the error's valid values)
Check for typos, casing, and stray whitespace/quotes in the export
Alternatively drop the override and let auto-detection find an installed CLI, or export an API key (ANTHROPIC_API_KEY/OPENAI_API_KEY/GEMINI_API_KEY), or pass --model explicitly

Example fix

# before
export HEADROOM_LEARN_CLI=claude-code  # typo'd name
headroom learn

# after
export HEADROOM_LEARN_CLI=claude
headroom learn

Defensive patterns

Strategy: validation

Validate before calling

import os, shutil
VALID = {'claude', 'gemini', 'codex'}  # keep in sync with the error's valid list
cli = os.environ.get('HEADROOM_LEARN_CLI')
if cli is not None and cli not in VALID:
    raise SystemExit(f'HEADROOM_LEARN_CLI={cli!r} invalid; choose from {sorted(VALID)}')

Try / catch

try:
    headroom_learn()
except ValueError as e:
    if 'HEADROOM_LEARN_CLI' in str(e):
        # correct the env var and retry once
        os.environ['HEADROOM_LEARN_CLI'] = 'claude'
        headroom_learn()
    else:
        raise

Prevention

Strip whitespace and lowercase the env var value when setting it
Validate HEADROOM_LEARN_CLI in a config-lint step before running learn
Read the error message — it lists the exact valid values for your headroom version

When it happens

Trigger: Running `headroom learn` (or calling the backend resolver) with HEADROOM_LEARN_CLI set to a typo'd or unsupported value, e.g. HEADROOM_LEARN_CLI=claude-code, claude_cli, 'Claude', or an arbitrary binary name, while no API key env vars are set.

Common situations: Copying the env var from docs for a different headroom version whose backend list changed; using quotes/whitespace in shell export ('claude ' with trailing space); assuming any CLI name works because auto-detection mentioned it; case sensitivity.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/9294266be954b12d. Report an issue: GitHub.