headroomlabs-ai/headroom · error · SystemExit

Error: 'kimi' (or 'kimi-cli') not found in PATH.

Error message

Error: 'kimi' (or 'kimi-cli') not found in PATH.

What it means

Before wrapping Kimi CLI, Headroom resolves the binary by trying shutil.which('kimi') first and shutil.which('kimi-cli') as fallback. Only if BOTH fail does it print this error with the MoonshotAI kimi-cli GitHub URL and raise SystemExit(1), before building the Kimi launch environment or starting the proxy. Guarded by the prepare_only early return.

Source

Thrown at headroom/cli/wrap.py:6270

    Sets KIMI_BASE_URL to route Kimi's OpenAI-compatible /chat/completions
    traffic through Headroom. Kimi's own OAuth bearer is forwarded upstream,
    so no extra login is required — run `kimi` once to authenticate first.

    \b
    Examples:
        headroom wrap kimi                         # Start proxy + kimi
        headroom wrap kimi -- -m kimi-for-coding   # Pass args to kimi
        headroom wrap kimi --port 9999             # Custom proxy port
        headroom wrap kimi --kimi-api-url https://api.moonshot.ai/v1
    """
    if prepare_only:
        return

    kimi_bin = shutil.which("kimi") or shutil.which("kimi-cli")
    if not kimi_bin:
        click.echo("Error: 'kimi' (or 'kimi-cli') not found in PATH.")
        click.echo("Install Kimi CLI: https://github.com/MoonshotAI/kimi-cli")
        raise SystemExit(1)

    env, env_vars_display = _build_kimi_launch_env(
        port, os.environ, project=_project_name_from_cwd()
    )

    _launch_tool(
        binary=kimi_bin,
        args=kimi_args,
        env=env,
        port=port,
        no_proxy=no_proxy,
        tool_label="KIMI",
        env_vars_display=env_vars_display,
        learn=learn,
        memory=memory,
        agent_type="kimi",
        code_graph=code_graph,
        openai_api_url=kimi_api_url,

View on GitHub (pinned to 322425c43b)

Solutions

1. Install Kimi CLI per https://github.com/MoonshotAI/kimi-cli
2. Verify either name resolves: `which kimi || which kimi-cli` in the same shell
3. Fix PATH for node-based installs (nvm use, or export the npm global bin dir), then `hash -r`
4. Use --prepare-only to prepare proxy/config without launching the CLI

Example fix

# before
headroom wrap kimi
# Error: 'kimi' (or 'kimi-cli') not found in PATH.

# after
# install per github.com/MoonshotAI/kimi-cli, then:
which kimi && headroom wrap kimi -- -m kimi-for-coding

import shutil

if not (shutil.which("kimi") or shutil.which("kimi-cli")):
    raise SystemExit("Install Kimi CLI first: https://github.com/MoonshotAI/kimi-cli")

import shutil

def kimi_available() -> bool:
    """True when either the kimi or kimi-cli binary is resolvable on PATH."""
    return shutil.which("kimi") is not None or shutil.which("kimi-cli") is not None

When it happens

Trigger: Running `headroom wrap kimi` (without --prepare-only) on a machine where neither `kimi` nor `kimi-cli` is installed or resolvable on PATH — e.g. the CLI never installed, or installed via npm under a node version whose bin dir the current shell doesn't have.

Common situations: kimi-cli not yet installed; installed globally with npm but the shell lacks the npm global bin path; renamed binaries across kimi-cli versions (hence the dual-name lookup) leaving neither name resolvable after an upgrade.

Related errors

• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.
• Error: 'codex' not found in PATH.
• Error: 'aider' not found in PATH.
• Error: 'openclaude' not found in PATH.

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