casa

README

casa

make any machine feel like home.

casa manages your machines — files, tools, and secrets — from one git repo, with two verbs: push and pull.

casa is a machine manager for developers who work across more than one Mac or Linux box. One git repo holds your dotfiles. One manifest declares every package — brew, distro, go, uv, npm, bun, cargo. Your secrets travel age-encrypted, with keys that never touch a repo. It converges instead of accumulates: casa pull pushes your changes first, reviews drift, upgrades packages, and actually uninstalls whatever you removed from the manifest. A fresh machine is one curl away from being yours.

Highlights

• 🏠 One menu for everything: edit files, install tools, manage secrets, push and pull machines — grouped, filterable, single keypress each.
• 📦 One package manifest: everything you install lands in .casadata/packages.toml; every machine converges on it with casa pull (brew, casks, taps, go, uv, npm, bun, cargo, and curl | sh installers).
• 📋 Paste any install command: go install …, cargo install …, bun add -g …, curl … | sh — casa detects the manager and records it. Install directly in your terminal and casa notices the drift.
• 🔁 Converges instead of accumulates: remove an entry from the manifest and the next pull uninstalls it. No Brewfile, no leftovers.
• 🔐 Encryption with zero key metadata in the repo: keys are files in ~/.config/casa/keys/; recipients are derived, never stored. Multiple keys, per-file choice, safe deletion with orphan re-encryption, passphrase-sealed repo backups, doppler support.
• 🧰 Repos carry data, casa carries behavior: the run scripts that install packages and restore keys are generated from the casa you're running — they never live in (or go stale in) your repo.
• 🖥️ Fresh machines from nothing: one command installs Homebrew if needed, casa, your keys, and every tool — a passphrase is all you carry.
• ⌨️ Consistent controls: type to filter, tab select, enter submit, esc/← back. Paths shown as ~/… everywhere.

Installation

One line on a brand-new machine (installs Homebrew if needed, installs casa, then runs casa machine setup against your repo):

curl -fsSL https://raw.githubusercontent.com/carrots-sh/casa/main/install.sh | sh -s -- <your-github-username>

Or just the binary:

# Homebrew
brew install carrots-sh/tap/casa

# Go
go install github.com/carrots-sh/casa/cmd/casa@latest

Release binaries for macOS and Linux (arm64/amd64, plus .deb/.rpm) are on the releases page. casa updates itself with casa upgrade.

Quickstart

casa

On a machine with nothing set up, that single command walks you through everything: installing dependencies, cloning your repo (or starting one), your setup questions, and key restore. On a working machine it opens the menu:

casa · your-machine

files     edit         · pick + edit a file — encrypted handled
          list         · managed files
          add          · start managing a file
          drift        · review local differences
          storage      · how a file is stored
          remove       · stop managing a file
tools     add          · install a tool (search or paste)
          list         · recorded tools
          update       · upgrade outdated tools   (3 updates)
          import       · record what's installed here
secrets   edit · list · add · keys · remove
machine   push         · publish your changes     (2 to push)
          pull         · update this machine
          status · answers · question · undo · setup · doctor · info
casa      upgrade · quit

One verb vocabulary everywhere: add, edit, remove, list mean the same thing in every cluster — no synonym verbs to learn (tracking a file is just files add). edit handles encrypted files transparently.

Everything in the menu is also a typed command:

usage: casa [command]           (no command opens the interactive menu)
shortcuts: casa edit [name] · casa push [msg] · casa pull · casa status
           casa cd · casa upgrade
files:   edit [name] · add [path] · drift · storage [name] · remove [path] · list
tools:   add [manager] [name] · add sh · add cmd ["command"] · remove · update · list · import · trust
secrets: add [path] · edit [name] · remove · keys · list
machine: setup [repo] · pull · push [message] · status · answers [name] · question · undo · doctor · info

(save/sync/configs/track/untrack/rm still work as legacy aliases.)

Features

Tools

Every tool you install through casa is recorded in one hand-editable manifest; casa pull converges any machine onto it (installs what's missing, uninstalls what you deleted). Search across managers, paste a full install command, or record a curl | sh installer with its own update command:

casa tools add                       # search brew/cask/npm/cargo, or paste a command
casa tools add cmd "go install golang.org/x/tools/gopls@latest"
casa tools import                    # record things you installed directly

See docs/tools.md.

Secrets & keys

Files are encrypted with age; private keys live in ~/.config/casa/keys/ and nothing about them — names, paths, recipients — ever enters a repo. Create keys, pick which one seals each secret, delete keys safely (casa finds files only that key can open and re-encrypts them first), and carry keys between machines via a passphrase-sealed repo backup, scp, or doppler.

casa secrets add ~/.aws/credentials
casa secrets keys                    # create · default · backup · delete · doppler

See docs/secrets.md.

Files & templates

Track a file and casa asks how to store it — plain, template (per-machine values auto-substituted), encrypted, or both — with sensible defaults detected from the file itself. Your repo's setup questions are asked in casa's UI and become {{ .variables }} usable in any template:

casa files add ~/.gitconfig          # heuristics suggest template (it has your email)
casa machine question                # add a setup question, use {{ .key }} anywhere
casa machine answers                 # change an answer, re-render this machine

See docs/configs.md.

Machines

casa machine setup <user>            # provision from <user>/dotfiles
casa pull                            # push yours, review drift, upgrade, apply
casa push                            # commit + push (auto-written message)
casa machine doctor                  # deps table + chezmoi doctor

See docs/machine.md and docs/getting-started.md for the fresh-VPS walkthrough.

Agent skill

Teach your coding agent to drive casa (Claude Code, Cursor, Codex, and ~50 others auto-detected):

bunx skills add carrots-sh/casa

That installs the whole suite from skills/: casa (the mental model, agent-safe flows, and routing) plus deep-dive skills for each domain — casa-files, casa-tools, casa-secrets, and casa-machine — with exact non-interactive command forms and the guardrails (no Brewfiles, no chezmoi-named commits, secrets stay human).

Documentation

Full documentation lives in docs/: getting started · installation · tools · secrets & keys · configs · machine · repo layout · CLI reference · design

Design

• Under the hood, chezmoi renders and applies your files — and your repo stays a valid chezmoi repo, so you can leave casa at any time and keep everything.
• Repos commit casa-named special files (.casa.toml.tmpl, .casaignore, .casadata/); casa maintains gitignored symlinks to the names chezmoi expects, self-healing before every chezmoi call.
• Repos carry only data. The run scripts that turn the manifest into installs are generated from the installed casa's templates — behavior always matches your casa version.
• See docs/design.md for the trade-offs, honestly stated.

Versioning

Semver: vMAJOR.MINOR.PATCH. See CHANGELOG.md.

License

MIT