Knowledge Islands

Projects / rig

A declarative description manager for a person's working setup.

Records preferred tools, what they are for and why they belong, resolves named profiles for machines and roles, and compares declared intent against what each provider actually observes.

Released command-line tool · currently published as v0.2.0 · preview

The problem

What this is for.

A working setup is spread across a Brewfile, a dotfiles repository, a language toolchain manager and a few download scripts, none of which can answer "what is my setup, and why is this here?". Rig gives those separate answers one catalogue and one set of profiles, then compares what you declared against what the machine actually has.

Whose problem

Whether it is yours.

You want this if you run more than one machine, or keep rebuilding one, and would rather the reasoning behind each tool were recorded than rediscovered. It is equally for the case where you need to hand someone a description of a setup without handing them your private machine state.

Capabilities

What it actually does.

  • A catalogue describing each tool: category, purpose, rationale, relationships and platforms.
  • Managed resources: services, scheduled jobs, typed machine settings and semantic layouts, declared together with their desired state.
  • Profiles that select a subset of that catalogue for a machine, a role or a context.
  • status and doctor: compare the selected profile against what Homebrew, uv, mise, npm, chezmoi, launchd and macOS defaults actually observe, reporting what is present, missing, drifted, unavailable or unknown.
  • apply, bootstrap, update and maintain: preview a complete plan, then let the native managers act on it.
  • export and publish: one deliberately public, allow-listed profile, shareable without exposing private machine state.

State

How finished it is.

Published as v0.2.0 and labelled preview. Configuration is inert TOML that Rig never sources as shell code, external provider operations require an explicit allow-listed declaration, and read-only inspection stays separate from mutation and publication.

Using it

How to start.

Install it, declare the tools and profiles you want, then compare that declaration against what each provider actually reports.

Prefer Homebrew.

The Knowledge Islands tap packages rig, so Homebrew owns upgrades and removal. Naming the tap in the argument taps it implicitly.

brew install knowledgeislands/tap/rig

Or use the stable installer endpoint.

The URL below is this site's stable machine route. It redirects to the installer published at v0.2.0 in the source repository, which owns the installer's behaviour and any signature or checksum verification it performs.

curl -fsSL https://knowledgeislands.info/install/rig | sh

Boundaries

What it deliberately does not do.

Rig is a manager of managers: it describes the whole and coordinates the parts, while the native systems still install and configure their own tools. It replaces no package manifest, no chezmoi source state, no provider credential store and no native configuration — and it installs nothing on your behalf without an explicit apply.

Authority

What this repository owns.

Owns the declared description of a working setup and the comparison between that intent and what providers observe. It installs nothing on your behalf.

That boundary is deliberate. The ecosystem separates philosophy, engineering discipline, capability semantics, portable standards, and executable behaviour so that none of them can quietly absorb another. The full directory shows where this project sits relative to the rest.

Nearby

The rest of the released set.

  • ki — The Knowledge Islands command-line interface.
  • mgit — Run commands across many Git repositories at once.
  • git-almanac — Inspect one local Git repository's calendars, authors and reports offline.

See every public project, or go straight to the released command-line tools.