Statemate

Declarative system configuration management. Manage dotfiles, configs, and packages across machines.

Features

• Stow-style sources — organize configs by app, deployed relative to home
• Profiles — machine-specific configs with auto-detection
• Templates — Go templates with the sprig function library
• Encryption — age encryption for sensitive files
• Secrets — Bitwarden references resolved from an encrypted cache
• Packages — declarative package management (brew, pacman, AUR)
• Scripts and hooks — run setup once, on a schedule, or when matching files change
• System files — manage /etc with ownership and sudo handled for you

Installation

# Homebrew (macOS/Linux)
brew install subbeh/tap/statemate

# Arch (AUR)
yay -S statemate-bin            # or: paru -S statemate-bin

# Go 1.25+
go install github.com/subbeh/statemate/cmd/mate@latest

Prebuilt binaries for Linux and macOS are on the releases page.

Quick Start

mkdir ~/dotfiles && cd ~/dotfiles
mate init                      # create mate.yaml and register the repository

mkdir nvim                     # a source, then list it: sources: [nvim]
mate add ~/.config/nvim/init.lua

mate status                    # what would change
mate diff                      # how it would change
mate apply                     # make it so

A source directory is deployed relative to your home directory:

~/dotfiles/
  mate.yaml
  nvim/
    .config/nvim/init.lua      →  ~/.config/nvim/init.lua
  zsh/
    .zshrc                     →  ~/.zshrc

Behavior is controlled by # suffixes on filenames, stripped from the target:

.ssh/config#encrypted#perm:600         encrypted in the repo, mode 0600 deployed
.gitconfig#template                    rendered as a Go template
.gitconfig#profile:work                only on machines matching the work profile
.claude/settings.json#import           app owns it; changes flow back to the repo

Documentation

Full documentation is at subbeh.github.io/statemate, built from docs/:

Guide	Contents
Getting Started	Install, create a repository, add your first file
Concepts	Sources, targets, state, and how a change is detected
How-to guides	Repository layout, multiple machines, encryption, system files, new machines, tips
Configuration	mate.yaml, .mate.yaml, profiles, local overrides
File Attributes	Every # suffix and what it does
Templates	Variables and functions available when rendering
Secrets	Bitwarden references and the encrypted cache
Scripts	Lifecycle scripts, frequency, timing
Hooks	Commands run when files matching a pattern change
Packages	Declarative packages across brew, pacman, and the AUR
Command Reference	Every command and flag

mate <command> --help gives the same reference in the terminal.

Configuration at a glance

# mate.yaml
sources: [nvim, zsh, git]

profiles:
  macos:
    detection:
      os: darwin
  work:
    extends: macos
    detection:
      hostname: "work-*"
    variables:
      email: "me@company.com"
    packages:
      brew: [slack]

age:
  identity: "~/.config/statemate/key.txt"
  recipients: ["age1..."]

packages:
  brew: [ripgrep, fd]

See Configuration for every key.

Shell Completions

mate completion bash > /etc/bash_completion.d/mate
mate completion zsh > "${fpath[1]}/_mate"
mate completion fish > ~/.config/fish/completions/mate.fish

Contributing

See CONTRIBUTING.md. In short: make test and make lint must pass, user-visible changes need a CHANGELOG entry, and make docs regenerates the command reference when help text changes.

License

MIT