grim

A grimoire for your machines. Declarative, cross-platform environment management in a single Rust CLI.

Documentation · Concepts · Roadmap · Decisions

---

grim reads a grimoire — a repository of declarative configuration — and casts it onto the current machine: installing packages across every package manager, rendering config files from templates, wiring up secrets, and isolating per-platform install trees so one shared $HOME can serve a fleet of heterogeneous machines.

The engine and the configuration are deliberately separate:

Thing	What it is	Example
grim	the engine (this repo) — a single CLI	grim apply, grim sync, grim doctor
a grimoire	your data — a repo grim reads	a dotfiles repo

A dotfiles repo is just a grimoire. Your work machine's private repo is another grimoire that extends the public one and overrides it. Same engine, layered data.

Why

A typical dotfiles setup is a clean declarative file layer sitting on a pile of untyped, untested shell that does the real work — package orchestration, platform detection, config merging, secret loading. It works until it drifts. grim moves that logic into one typed, tested Rust binary built on a few clean abstractions:

• Facts — the machine, probed once into a typed struct.
• Platforms — named, precedence-ordered layers matched against facts. A dev container is just a high-precedence platform. (concept)
• Packages — one canonical id resolved to the best provider (brew / cargo / uv / npm / go / …) for the current platform stack. (concept)
• Apply — a scoped templating + file-placement engine. (concept)
• Secrets — optional, pluggable providers (1Password, age/sops, plain env). Core works with none. (concept)

Install

grim is green-field and pre-0.1; install from source.

git clone https://github.com/alkemdev/grim
cd grim
cargo install --path crates/grim

Quickstart

grim facts                                # probe this machine into typed Facts
grim stack --grimoire examples/demo       # resolve the active platform stack
grim diff  --grimoire examples/demo --target /tmp/grim-demo   # preview the file apply
grim apply --grimoire examples/demo --target /tmp/grim-demo   # render and place the files

$ grim stack --grimoire examples/demo
active platform stack (highest precedence first):
  1000  devcontainer       Container
   900  workstation        Host
   400  cuda               Hardware
   100  linux              Os

Status

Early. The detect → load → resolve core is built and tested; the apply, packages, and secrets layers are landing per the roadmap. The design is documented in the open under docs/ and recorded in decision records.

Layout

crates/
  grim-core/   pure logic: facts, platforms, precedence, manifests, resolution
  grim/        the CLI binary
docs/          architecture, concepts, guides, decisions (source for grim.alkem.dev)
examples/      example grimoires

Contributing

See CONTRIBUTING.md (and AGENTS.md if you're a coding agent). The short version: grim-core stays pure, just check stays green, and decisions get an ADR.

License

MIT — see LICENSE-MIT.