klim

module

v0.1.3 Latest Latest Go to latest Published: May 13, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/nassiharel/klim

Links

Open Source Insights

README ¶

klim

Reignite Dev Experience.

Klim is a productivity booster for dev tools: a deterministic, cross-platform layer for discovering, standardizing, securing, and automating the tools every project depends on. It keeps native package managers in charge of installation while giving humans, teams, CI, and AI agents the same portable environment contracts and predictable operations.

Quick install

macOS / Linux

# Recommended — installer script
curl -fsSL https://raw.githubusercontent.com/nassiharel/klim/main/install.sh | bash

# Homebrew tap
brew install nassiharel/tap/klim

Windows

# Recommended — installer script
irm https://raw.githubusercontent.com/nassiharel/klim/main/install.ps1 | iex

# winget
winget install nassiharel.klim

# Scoop bucket
scoop bucket add nassiharel https://github.com/nassiharel/scoop-bucket
scoop install klim

Any OS with Go 1.25+

go install github.com/nassiharel/klim/cmd/klim@latest

Verify

klim version

Other install options (deb / rpm / direct binary)

Debian / Ubuntu

# Replace <arch> with amd64 or arm64
curl -LO https://github.com/nassiharel/klim/releases/latest/download/klim_<version>_linux_<arch>.deb
sudo dpkg -i klim_<version>_linux_<arch>.deb

Fedora / CentOS / RHEL

# Replace <arch> with amd64 or arm64
curl -LO https://github.com/nassiharel/klim/releases/latest/download/klim_<version>_linux_<arch>.rpm
sudo rpm -i klim_<version>_linux_<arch>.rpm

Direct binary

Pre-built archives for every platform are attached to each GitHub Release:

klim_<version>_darwin_amd64.tar.gz / klim_<version>_darwin_arm64.tar.gz
klim_<version>_linux_amd64.tar.gz / klim_<version>_linux_arm64.tar.gz
klim_<version>_windows_amd64.zip

Each archive ships with a CycloneDX SBOM (*.sbom.json) and an entry in the release's checksums.txt. Verify a download with:

sha256sum klim_<version>_<platform>.tar.gz
# compare against checksums.txt

Pin a specific version

# install.sh — bash flag
curl -fsSL https://raw.githubusercontent.com/nassiharel/klim/main/install.sh | bash -s -- --version v0.1.2

# install.ps1 — env var
$env:CLIM_VERSION = "v0.1.2"
irm https://raw.githubusercontent.com/nassiharel/klim/main/install.ps1 | iex

# go install — version suffix
go install github.com/nassiharel/klim/cmd/klim@v0.1.2

# brew / winget / scoop — pin via the package manager itself
brew install nassiharel/tap/klim@0.1.2
winget install nassiharel.klim --version 0.1.2
scoop install klim@0.1.2

Or download the matching archive from the tagged release page directly.

Launch the interactive TUI:

klim

Or use deterministic commands from scripts, CI, or agents:

klim check --output json
klim diff teammate.yaml
klim security audit --sbom
klim install --pack go-developer

What Klim gives you

Map your environment

Klim scans your PATH and native package managers to show installed developer tools, versions, install sources, binary paths, GitHub metadata, project references, pack membership, and update status.

Standardize project requirements

Drop a .klim.yaml in a repo to define required and optional tools with version constraints. klim check validates every developer's environment locally or in CI, and klim init can generate the contract from project files such as package.json, go.mod, Dockerfiles, CI workflows, Helm charts, Terraform, Bicep, and more.

Reproduce and move toolchains

Export, import, share, diff, and capture environment snapshots. Klim maps tools to the best available package manager on each OS, so a known-good setup can move between macOS, Linux, Windows, containers, and teammates.

Automate through native package managers

Klim delegates installs and upgrades to the package managers you already trust: winget, Homebrew, apt, Chocolatey, Scoop, snap, and npm. It adds selection, planning, JSON output, exit codes, dry runs, packs, and cross-manager visibility without replacing those managers.

Audit trust and security

Run health checks, security audits, license inventory, vulnerability scans, and CycloneDX SBOM generation across your toolchain. Klim flags PATH problems, unmanaged installs, archived upstreams, stale repositories, missing versions, and known CVEs/GHSAs.

Give agents deterministic primitives

AI agents are good at translating intent. Klim is the stable local primitive they should call for environment operations. Instead of asking an agent to improvise package-manager commands, let it run klim check, klim install, klim diff, or klim security audit --output json and parse predictable results.

Screenshots

Installed _{Every tool, every version, every install source}	Dashboard _{Score, coverage, GitHub highlights, package-manager mix}
Marketplace _{110+ curated tools with category, stars, and policy state}	Curated packs _{Bundle status across Cloud Essentials, Kubernetes Starter, Go Developer, …}
For You _{Personalised recommendations ranked by overlap with your installed set}	Project scan _{Auto-detect required tools from go.mod, package.json, .github/}
Compliance _{Disallowed sources, blocked tools, license violations against your active policy}	Local browser _{klim browser — same data and actions as the TUI in your default browser}

Nine TUI tabs and an optional local web view. Same data, same actions, same JSON — whichever surface you prefer.

Core workflows

Workflow	Commands
Map this machine	`klim`, `klim list`, `klim info kubectl`
Standardize a project	`klim init`, `klim check`, `klim generate github-action`
Reproduce an environment	`klim export`, `klim import`, `klim env show`, `klim env apply`
Compare machines	`klim diff baseline.yaml`, `klim trail capture`, `klim trail diff`
Audit and score	`klim health`, `klim health path`, `klim security audit`, `klim score`, `klim security vuln`
Preview and apply	`klim plan`, `klim apply`, `klim checkpoint <name>`, `klim rollback <name>`
Automate installs	`klim install jq`, `klim upgrade --pack go-developer`, `klim remove jq`, `klim watch`
Agent-safe execution	`klim check --output json`, `klim install --dry-run --output json`

Feature map

Interactive TUI: My Tools, Marketplace, Project, Dashboard, My Profile (with My Score breakdown), Health (PATH conflict explorer + interactive fix wizard), Security, Backup, and Config views.
Plan / apply / rollback: Terraform-style preview (klim plan) with confidence scoring, auto-checkpointed execution (klim apply) with shell-resolution + binary-validation + PATH-consistency + manager-integrity postcheck, and named snapshot management (klim checkpoint, klim rollback).
Marketplace and packs: Browse 110+ curated developer tools, install bundles, and create custom packs.
Team manifests: Versioned .klim.yaml contracts for local checks, CI, generated workflows, Dockerfiles, and devcontainers.
Environment tokens: klim env captures tools, favorites, custom packs, package managers, Klim version, OS, and security state into a privacy-safe token.
Backup and sharing: Manifest exports, share tokens, saved backups, cross-machine imports, OS-aware package-manager mapping, and PATH backups captured before any Health-tab PATH fix runs.
Toolchain history: klim trail captures content-addressed snapshots that can be labeled, diffed, pruned, and compared over time.
Environment diff: Compare local tools against manifests or tokens and see matches, version differences, local-only tools, and remote-only tools.
Security and compliance: Health checks with interactive remediation, audits, vulnerability lookup through OSV.dev, license inventory, policy enforcement, and SBOM output.
Shell integration: Native completions and hooks that automatically run .klim.yaml checks when you enter a project.
Auto-install shims: klim proxy creates lightweight shims that install missing tools on first use through the best available package manager.
Onboarding and discovery: Role-based recommendations, related-tool suggestions, klim why, and klim try for temporary installs.
Custom marketplaces: Merge extra catalog URLs with the default marketplace for internal or community tool definitions.

Why not just use an agent with shell access?

Agents can translate fuzzy intent into commands, but environment operations need determinism, auditability, local privacy, and stable artifacts. Klim and agents solve different parts of the problem.

Where agents help

Turning ambiguous requests into concrete tasks.
Explaining unfamiliar tools and trade-offs.
Composing multi-step plans across repositories.

Where Klim should be the primitive

Determinism: klim install --pack go-developer --output json exits the same way every time. A prompt does not.
Trust boundary: Klim uses a curated, versioned catalog and native package managers instead of arbitrary curl | bash suggestions from model context.
Compliance as code: .klim.yaml and policy files are reviewable contracts. Prompt instructions are not auditable controls.
Privacy and offline use: Tool inventories, project requirements, paths, and policies stay local unless you explicitly export or share them.
Stable artifacts: Manifests, share tokens, env tokens, trail snapshots, and JSON output outlive a chat session.
CI safety: Klim has stable exit codes and schemas without token spend or model drift.

The honest framing: agents handle judgment calls; Klim handles operations that must be the same every time.

Architecture

Klim is written in Go with a Bubble Tea TUI and Cobra CLI. The runtime flow is:

ToolService
  -> ToolCatalog     fetch/cache marketplace.yaml from GitHub
  -> ToolFinder      scan PATH and detect install sources
  -> VersionResolver query native package managers for installed/latest versions

Version data comes from native package managers, not a private registry:

Package manager	Platforms	Used for
winget	Windows	Installed and latest versions
Chocolatey	Windows	Installed and latest versions
Homebrew	macOS, Linux	Installed and latest versions
apt / dpkg	Debian/Ubuntu	Installed and latest versions
snap	Linux	Installed and latest versions
npm	All	Installed and latest versions

The marketplace is fetched from https://raw.githubusercontent.com/nassiharel/klim/marketplace/marketplace.yaml and cached locally for offline use.

Configuration

Klim stores user data under ~/.klim/ (same path on macOS, Linux, and Windows). The marketplace cache lives at ~/.klim/marketplace/marketplace-cache.yaml.

Use:

klim config path
klim config edit

Troubleshooting

Problem	Solution
`klim: command not found`	Ensure the install directory is in `PATH`. Use `which klim` on macOS/Linux or `where klim` on Windows.
Tool not detected	Verify the binary is in `PATH`, then run `klim` and press `r` or use `--refresh` on CLI commands.
Permission denied on upgrade	The native package manager may need elevated privileges. Use `sudo` or an Administrator shell where appropriate.
Stale version info	Run `klim security health`, use `--refresh`, or clear the scan cache.
Self-update fails	Download the latest archive from Releases and replace the binary manually.

Contributing

Contributions are welcome. See AGENTS.md for architecture, conventions, and development commands.

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
klim command
internal
audit Package audit provides shared security audit logic used by both the CLI (klim audit) and TUI (Doctor→Audit sub-tab).	Package audit provides shared security audit logic used by both the CLI (klim audit) and TUI (Doctor→Audit sub-tab).
build
catalog Package catalog manages fetching, caching, and diffing the tool marketplace catalog from GitHub.	Package catalog manages fetching, caching, and diffing the tool marketplace catalog from GitHub.
checkpoint Package checkpoint captures named snapshots of the installed toolchain so they can be rolled back to later.	Package checkpoint captures named snapshots of the installed toolchain so they can be rolled back to later.
cli
compliance Package compliance validates installed tools against a company policy file.	Package compliance validates installed tools against a company policy file.
config Package config manages the klim configuration file (config.yaml).	Package config manages the klim configuration file (config.yaml).
custompacks Package custompacks manages user-created pack definitions stored in ~/.klim/marketplace/custom-packs.yaml.	Package custompacks manages user-created pack definitions stored in ~/.klim/marketplace/custom-packs.yaml.
detector
doctor Package doctor runs environment health checks and reports diagnostic issues.	Package doctor runs environment health checks and reports diagnostic issues.
envid Package envid produces a portable, paste-friendly fingerprint of a klim-managed environment ("Env ID").	Package envid produces a portable, paste-friendly fingerprint of a klim-managed environment ("Env ID").
favorites Package favorites manages the user's favorites list stored in ~/.klim/favorites/favorites.yaml.	Package favorites manages the user's favorites list stored in ~/.klim/favorites/favorites.yaml.
fileutil Package fileutil provides shared file I/O primitives for klim: atomic writes, YAML serialization, and directory helpers.	Package fileutil provides shared file I/O primitives for klim: atomic writes, YAML serialization, and directory helpers.
finder
generate Package generate produces CI/container configuration files from .klim.yaml tool requirements and marketplace package definitions.	Package generate produces CI/container configuration files from .klim.yaml tool requirements and marketplace package definitions.
githubfmt Package githubfmt formats GitHub project metadata (star counts, push dates, repo URLs) for display.	Package githubfmt formats GitHub project metadata (star counts, push dates, repo URLs) for display.
logging Package logging sets up structured logging for klim using log/slog.	Package logging sets up structured logging for klim using log/slog.
manifest Package manifest defines the shared YAML schema for tool export/import manifests.	Package manifest defines the shared YAML schema for tool export/import manifests.
marketplace/assemble command assemble-marketplace reads individual tool and pack YAML files from marketplace/tools/ and marketplace/packs/, and assembles them into a single marketplace.yaml matching the format the CLI expects.	assemble-marketplace reads individual tool and pack YAML files from marketplace/tools/ and marketplace/packs/, and assembles them into a single marketplace.yaml matching the format the CLI expects.
marketplace/livecheck Package livecheck contains the opt-in integration test that verifies each package ID declared in marketplace/tools/*.yaml resolves against the corresponding native package manager (winget, choco, scoop, brew, apt, snap, npm).	Package livecheck contains the opt-in integration test that verifies each package ID declared in marketplace/tools/*.yaml resolves against the corresponding native package manager (winget, choco, scoop, brew, apt, snap, npm).
marketplace/validate command validate-marketplace validates individual tool and pack YAML files in the marketplace/ directory.	validate-marketplace validates individual tool and pack YAML files in the marketplace/ directory.
onboard Package onboard provides role-based tool recommendation logic shared between the CLI wizard and TUI onboard sub-tab.	Package onboard provides role-based tool recommendation logic shared between the CLI wizard and TUI onboard sub-tab.
pathbackup Package pathbackup captures the value of $PATH (and the persistent User PATH on Windows) before klim applies any PATH-modifying fix, and produces shell-specific restore commands so the user can roll back without leaving the TUI.	Package pathbackup captures the value of $PATH (and the persistent User PATH on Windows) before klim applies any PATH-modifying fix, and produces shell-specific restore commands so the user can roll back without leaving the TUI.
pathconflict Package pathconflict derives a structured view of PATH-shadowing and version-conflict situations from an already-scanned tool slice.	Package pathconflict derives a structured view of PATH-shadowing and version-conflict situations from an already-scanned tool slice.
paths Package paths provides a single source of truth for all klim configuration and data file paths.	Package paths provides a single source of truth for all klim configuration and data file paths.
pkgmgr
plan Package plan computes a "Terraform plan" for developer machines: given the current state of installed tools and a desired target (latest versions, a manifest, or an explicit tool list), it returns a structured Plan describing every change that would be made, along with risk warnings, disk-impact estimates, and a rough wall-clock time estimate.	Package plan computes a "Terraform plan" for developer machines: given the current state of installed tools and a desired target (latest versions, a manifest, or an explicit tool list), it returns a structured Plan describing every change that would be made, along with risk warnings, disk-impact estimates, and a rough wall-clock time estimate.
postcheck Package postcheck verifies that a klim apply left the developer machine in a working state.	Package postcheck verifies that a klim apply left the developer machine in a working state.
progress Package progress provides a simple CLI spinner for non-interactive commands.	Package progress provides a simple CLI spinner for non-interactive commands.
recommend Package recommend ranks not-installed tools by overlap with the user's currently installed set, so both the TUI's "For You" sub-tab and the web UI's /foryou page can suggest related tools using the same algorithm.	Package recommend ranks not-installed tools by overlap with the user's currently installed set, so both the TUI's "For You" sub-tab and the web UI's /foryou page can suggest related tools using the same algorithm.
registry
scancache Package scancache persists the result of a full tool scan (PATH discovery plus package-manager version resolution) to a YAML file on disk.	Package scancache persists the result of a full tool scan (PATH discovery plus package-manager version resolution) to a YAML file on disk.
score Package score computes a 0–100 environment health score by combining tool freshness, doctor diagnostics, audit findings, compliance status, and source management into a single metric.	Package score computes a 0–100 environment health score by combining tool freshness, doctor diagnostics, audit findings, compliance status, and source management into a single metric.
search Package search provides fuzzy search over the tool marketplace catalog.	Package search provides fuzzy search over the tool marketplace catalog.
security Package security computes a per-tool security verdict by aggregating signals from internal/audit, internal/vuln, internal/compliance, and the tool's installed source.	Package security computes a per-tool security verdict by aggregating signals from internal/audit, internal/vuln, internal/compliance, and the tool's installed source.
selfupdate
service Package service provides the ToolService — a high-level composition root that wires together tool catalog loading, PATH scanning, and version resolution into reusable pipelines.	Package service provides the ToolService — a high-level composition root that wires together tool catalog loading, PATH scanning, and version resolution into reusable pipelines.
share Package share provides compact token encoding for sharing tool lists via chat messages.	Package share provides compact token encoding for sharing tool lists via chat messages.
snapshot Package snapshot manages environment snapshots and named profiles.	Package snapshot manages environment snapshots and named profiles.
teamfile Package teamfile handles .klim.yaml team manifest files — parsing, discovery (walking parent dirs), and checking installed tools against version constraints.	Package teamfile handles .klim.yaml team manifest files — parsing, discovery (walking parent dirs), and checking installed tools against version constraints.
textwrap Package textwrap provides shared word-wrapping that respects terminal display width.	Package textwrap provides shared word-wrapping that respects terminal display width.
trail Package trail records every change to the local toolchain as a content-addressed environment snapshot, exposing git-style history inspection (capture, log, show, diff, prune).	Package trail records every change to the local toolchain as a content-addressed environment snapshot, exposing git-style history inspection (capture, log, show, diff, prune).
tui
vuln Package vuln looks up known vulnerabilities (CVEs / GHSAs) for the installed tools.	Package vuln looks up known vulnerabilities (CVEs / GHSAs) for the installed tools.
web Package web serves klim's local browser UI.	Package web serves klim's local browser UI.