Rig is a declarative description and manager of a person's working setup. It gives tools, agent skills, managed resources, and private port allocations one understandable catalogue, then compares that declared intent with the machine in front of you.
Rig answers questions such as:
- What is in my setup, and why did I choose it?
- Which parts belong on this machine or in this role?
- Which native system installs or observes each part?
- What is present, missing, drifted, unavailable, or unknown?
- Which deliberately public subset can I publish without exposing machine state?
Rig configuration owns desired package selection; Homebrew, uv, mise and npm are execution mechanisms, not competing package lists. Rig does not use Homebrew Bundle or require a Brewfile. Native systems retain resolution rules, credentials and installation state; chezmoi retains its source files, templates and application semantics.
- A catalogue records the identity, purpose, rationale, relationships, and supported platforms of each tool.
- A skill records a user-level agent capability and the native authority responsible for it.
- A managed resource records desired services, scheduled jobs, typed machine settings, and semantic layouts.
- A private port records stable TCP intent without opening, reserving, or publishing a socket.
- A profile selects a complete machine or role setup, or a non-appliable view such as a public subset.
- A provider is the native system that materialises or observes declared intent.
- State is Rig's comparison between a resolved profile and provider observations on the current machine.
That makes Rig a manager of managers beneath a catalogue people can read.
Rig is a pre-v1 public preview. The latest immutable release is v0.4.0:
curl -fsSL https://raw.githubusercontent.com/knowledgeislands/tools-rig/v0.4.0/install.sh | bash -s -- v0.4.0That command installs the released 0.4.0 contract.
To use the current checkout while developing or evaluating those changes, link both the executable and manual:
./install.sh --link
rig --version # rig 0.4.0+devThe development marker identifies an untagged checkout after the latest immutable release; it does not promise the next release number.
Follow Get started with Rig to write a small human-readable configuration, inspect it, check the machine, and preview the first application.
To preview just one declared change, use rig apply --target ID --dry-run; repeat --target to select several exact entries.
Use rig init for new, unversioned configuration and rig repair for a previewed legacy-schema repair proposal. rig show [ITEM] explains intent, rig status compares it with the machine, rig apply reconciles it, and rig upgrade advances declared software. rig capture prepares reviewed Homebrew additions; rig doctor evaluates health and rig diag gives share-safe facts. Export, help and completion remain utilities.
Use --format json with show, status, doctor, apply, or upgrade when a script needs complete values. status --retired adds private, informational evidence for explicitly retired applications, without cleanup or health findings. Capture emits discovery text or additive TOML. Existing users should follow the command migration guide; this release makes a breaking cutover without aliases.
The user-guide journey then introduces profiles, machine resources, user-level skills, provider boundaries, and publication in stages. Use man rig for the exhaustive command and configuration reference.
- User guides explain how to adopt and operate Rig.
- Developer guides explain how to change and release Rig.
- Decision Records explain durable architectural choices.
- Specifications define accepted, testable behaviour.
- Roadmap identifies canonical forward work.
Pull requests are welcome. Start with Develop Rig and use the definition of done before presenting a change for review.
MIT © 2026 Kris Brown.