{"record":{"id":"2b98f10408cda71a","repo":"headroomlabs-ai/headroom","slug":"error-kimi-or-kimi-cli-not-found-in-path","errorCode":null,"errorMessage":"Error: 'kimi' (or 'kimi-cli') not found in PATH.","messagePattern":"Error: 'kimi' \\(or 'kimi-cli'\\) not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":6270,"sourceCode":"    Sets KIMI_BASE_URL to route Kimi's OpenAI-compatible /chat/completions\n    traffic through Headroom. Kimi's own OAuth bearer is forwarded upstream,\n    so no extra login is required — run `kimi` once to authenticate first.\n\n    \\b\n    Examples:\n        headroom wrap kimi                         # Start proxy + kimi\n        headroom wrap kimi -- -m kimi-for-coding   # Pass args to kimi\n        headroom wrap kimi --port 9999             # Custom proxy port\n        headroom wrap kimi --kimi-api-url https://api.moonshot.ai/v1\n    \"\"\"\n    if prepare_only:\n        return\n\n    kimi_bin = shutil.which(\"kimi\") or shutil.which(\"kimi-cli\")\n    if not kimi_bin:\n        click.echo(\"Error: 'kimi' (or 'kimi-cli') not found in PATH.\")\n        click.echo(\"Install Kimi CLI: https://github.com/MoonshotAI/kimi-cli\")\n        raise SystemExit(1)\n\n    env, env_vars_display = _build_kimi_launch_env(\n        port, os.environ, project=_project_name_from_cwd()\n    )\n\n    _launch_tool(\n        binary=kimi_bin,\n        args=kimi_args,\n        env=env,\n        port=port,\n        no_proxy=no_proxy,\n        tool_label=\"KIMI\",\n        env_vars_display=env_vars_display,\n        learn=learn,\n        memory=memory,\n        agent_type=\"kimi\",\n        code_graph=code_graph,\n        openai_api_url=kimi_api_url,","sourceCodeStart":6252,"sourceCodeEnd":6288,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L6252-L6288","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Kimi CLI per https://github.com/MoonshotAI/kimi-cli","Verify either name resolves: `which kimi || which kimi-cli` in the same shell","Fix PATH for node-based installs (nvm use, or export the npm global bin dir), then `hash -r`","Use --prepare-only to prepare proxy/config without launching the CLI"],"exampleFix":"# before\nheadroom wrap kimi\n# Error: 'kimi' (or 'kimi-cli') not found in PATH.\n\n# after\n# install per github.com/MoonshotAI/kimi-cli, then:\nwhich kimi && headroom wrap kimi -- -m kimi-for-coding","handlingStrategy":"type-guard","validationCode":"import shutil\n\nif not (shutil.which(\"kimi\") or shutil.which(\"kimi-cli\")):\n    raise SystemExit(\"Install Kimi CLI first: https://github.com/MoonshotAI/kimi-cli\")","typeGuard":"import shutil\n\ndef kimi_available() -> bool:\n    \"\"\"True when either the kimi or kimi-cli binary is resolvable on PATH.\"\"\"\n    return shutil.which(\"kimi\") is not None or shutil.which(\"kimi-cli\") is not None","tryCatchPattern":null,"preventionTips":["Check both binary names: `which kimi || which kimi-cli`","After upgrading kimi-cli, verify which name the new version installs","Ensure the npm global bin dir is on PATH"],"tags":["path","installation","kimi","moonshot","cli","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}