Troubleshooting & FAQ
Common questions and quick fixes. If something here doesn’t cover your case, open a Discussion or issue.
Frequently asked questions
Section titled “Frequently asked questions”Does klim replace my package manager?
Section titled “Does klim replace my package manager?”No. klim is a cross-platform layer over the native managers you already trust — brew, winget, scoop, apt, choco, snap, and npm. It picks the right one per platform and delegates the actual install; it never reimplements package management.
Do I need an account, server, or to send telemetry?
Section titled “Do I need an account, server, or to send telemetry?”No. klim is a single binary. There is no account, no server, and no telemetry. Everything it
stores lives under ~/.klim/.
How is klim different from asdf / mise / devcontainers?
Section titled “How is klim different from asdf / mise / devcontainers?”asdf and mise manage language runtimes via their own shims. devcontainers need Docker. klim covers your whole tool set (CLIs, editors, cloud tools, databases…) across all three operating systems, using your native package managers — no new runtime and no container required. See the comparison on the website.
Where does klim store its data?
Section titled “Where does klim store its data?”Everything is under ~/.klim/ (%USERPROFILE%\.klim on Windows): config.yaml, the cached
marketplace catalog, scan cache, checkpoints, backups, and logs. Override the root with the
KLIM_HOME environment variable.
Troubleshooting
Section titled “Troubleshooting””command not found” after installing a tool
Section titled “”command not found” after installing a tool”A new tool’s directory may not be on your PATH yet, or your shell cached the old PATH.
Restart the shell, then run:
klim doctor path # show PATH conflicts and shadowed binariesklim doctor # full environment diagnosticsklim can’t load the marketplace catalog
Section titled “klim can’t load the marketplace catalog”The catalog is fetched from GitHub on first use and cached locally. If you’re offline with no cache, the catalog can’t load. Reconnect once and run:
klim tool search ripgrep --refresh # force a fresh catalog fetchVersions look stale or a tool shows “not installed” when it is
Section titled “Versions look stale or a tool shows “not installed” when it is”klim caches scan results per host for speed. Force a rescan:
klim tool list --refreshIn the TUI, press r to rescan.
Shell completions aren’t working
Section titled “Shell completions aren’t working”Completions ship in the release archives and Linux packages, or you can generate them directly:
klim shell completion bash # or zsh | fish | powershellSee shell completion for where to install the output for your shell.
An upgrade broke something — how do I roll back?
Section titled “An upgrade broke something — how do I roll back?”klim plan apply auto-creates a checkpoint before it changes anything. List and roll back:
klim plan checkpoint listklim plan rollback <checkpoint>See plan, apply, and rollback.
A PATH fix changed my environment and I want it back
Section titled “A PATH fix changed my environment and I want it back”Any Health-tab fix that touches PATH captures a backup first. Restore it with:
klim doctor path-backups listklim doctor path-backups restore-cmd <backup>Getting more help
Section titled “Getting more help”klim --helpandklim <command> --helpdocument every command and flag.- GitHub Discussions for questions and ideas.
- GitHub Issues for bugs and tool requests.