# cfgd
Declare your entire machine (packages, dotfiles, system settings, secrets) with composable profiles and shareable, cross-platform modules.
[](https://github.com/tj-smith47/cfgd/actions/workflows/ci.yml)
[](https://github.com/tj-smith47/cfgd/actions/workflows/e2e.yml)
[](https://github.com/tj-smith47/cfgd/actions/workflows/release.yml)
[](https://github.com/tj-smith47/cfgd/actions/workflows/ci.yml)
[](#license)
*A bare `ubuntu:24.04` container with no Neovim, no Homebrew and no config. One `cfgd init` later, `nvim` opens a fully configured LazyVim. Recorded with [VHS](https://github.com/charmbracelet/vhs).*
> **Status:** Alpha. APIs may change.
---
- [What is cfgd](#what-is-cfgd)
- [How It Works](#how-it-works)
- [Quick Start](#quick-start)
- [Why cfgd exists](#why-cfgd-exists)
- [Shareable Modules](#shareable-modules)
- [How cfgd compares](#how-cfgd-compares)
- [Features](#features)
- [Documentation](#documentation)
- [Distribution](#distribution)
---
## What is cfgd
Most dotfile managers track files. `cfgd` manages your entire machine. You declare packages, files, secrets, and system settings in version-controlled YAML. `cfgd` diffs what you want against what you have, builds a plan, and reconciles continuously. If something drifts, it is detected and corrected.
## How It Works
**Profiles** declare your machine's desired state: packages, files, system settings. They compose via inheritance: share a common base across machines, then specialize per context. See [docs/profiles.md](https://github.com/tj-smith47/cfgd/blob/HEAD/docs/profiles.md).
```
base
╱ ╲
work personal
╱ ╲
laptop devcontainer
```
**Modules** are shareable, self-contained config packages. Install someone else's dev environment or publish your own. Cross-platform package resolution picks the right manager automatically. See [docs/modules.md](https://github.com/tj-smith47/cfgd/blob/HEAD/docs/modules.md).
**Reconciliation** continuously ensures machines match their declared state. Drift is detected, reported, and optionally auto-corrected. Failed actions don't abort; they're logged and skipped. See [docs/reconciliation.md](https://github.com/tj-smith47/cfgd/blob/HEAD/docs/reconciliation.md), or watch [two machines converge through the daemon](https://github.com/tj-smith47/cfgd/blob/HEAD/docs/daemon.md#what-it-does).
## Quick Start
```sh
# Install via Homebrew
brew install tj-smith47/tap/cfgd
# Or via install script
curl -fsSL https://github.com/tj-smith47/cfgd/releases/latest/download/install.sh | sh
# Or via cargo
cargo install cfgd
# Bring your config to a new machine in seconds
cfgd init --from git@github.com:you/machine-config.git
# Or start fresh
cfgd init
# Or let AI scan your system and generate config for you
export ANTHROPIC_API_KEY=sk-...
cfgd generate
# Set up shell completions (add to your shell's rc file)
source <(cfgd completion bash) # .bashrc
source <(cfgd completion zsh) # .zshrc
cfgd completion fish | source # config.fish
```
## Why cfgd exists
I recently switched jobs, and spent the last week of my old job backing up scripts and dotfiles, parsing out company-specific info, and composing a tarball to transfer. At the new job, I spent another few days getting my new machine reconfigured. Over time I kept discovering things I'd forgotten, and things (System Settings, for one) I wished the backup had covered. It all felt manual and incomplete: I should be able to clone a repo and have my entire workstation (packages, scripts, dotfiles, system settings) feel familiar again. Better still, to keep parts of that feeling in sync between my home and work laptops.
The other inspiration was devcontainers. At my previous company I had set up custom scripts to inject dotfiles into the devcontainer so a user could replicate their dev environment once they shell in. At minimum, I wanted my full Neovim setup available in any ephemeral container without modifying the devcontainer config in every team's repository to accommodate it. I needed something that could bootstrap my config into any environment from the outside, regardless of whose repo I was working in. Plus, I had some coworkers in need of education about the superiority of vim-motions, and wanted a quick way to share my exact setup, down to the alias.
`cfgd` borrows from the best ideas across practices:
- **Kubernetes**: declarative reconciliation loop, KRM resource model
- **Terraform**: plan/apply workflow, state tracking, drift detection
- **Puppet**: continuous enforcement via daemon, module ecosystem
- **Nix**: reproducible machine state from a single source of truth
- **Ansible**: YAML-driven config management, idempotent task execution
- **Kustomize**: layered overrides and patches
- **chezmoi**: dotfile management
## Shareable Modules
This is my favorite feature: a single packaged config for a tool that works anywhere.
```sh
cfgd module create my-dev-env
cfgd profile update --module community/nvim
```
A module declares packages with cross-platform resolution, config files, shell environment variables and aliases, and lifecycle scripts:
```yaml
apiVersion: cfgd.io/v1alpha1
kind: Module
metadata:
name: nvim
description: Neovim editor configuration
spec:
depends: [node, python]
packages:
- name: neovim
minVersion: "0.10"
prefer: [brew, snap]
deny: [apt]
- name: ripgrep
- name: fd
aliases:
apt: fd-find
dnf: fd-find
- name: gcc
aliases:
apt: build-essential
dnf: "@development-tools"
platforms: [linux]
files:
- source: files/init.lua
target: ~/.config/nvim/init.lua
- source: files/lua
target: ~/.config/nvim/lua
env:
- name: EDITOR
value: nvim
aliases:
- name: v
command: nvim
scripts:
postApply:
- nvim --headless '+Lazy! sync' '+MasonToolsInstallSync' +qa
```
See [docs/modules.md](https://github.com/tj-smith47/cfgd/blob/HEAD/docs/modules.md) for the full spec including git file sources, registries, and dependency resolution.
## How cfgd compares
| | **cfgd** | [chezmoi](https://chezmoi.io) | [Nix Home Manager](https://nix-community.github.io/home-manager/) | [Ansible](https://docs.ansible.com/) | [Puppet](https://www.puppet.com/) |
|---|---|---|---|---|---|
| **Focus** | Full machine state | Dotfiles | Dotfiles + packages (Nix) | General automation | Server/infra state |
| **Packages** | **18 managers** | None | Nix only | Any (via tasks) | Any (via providers) |
| **Drift detection** | **Continuous (daemon)** | Manual | On rebuild | Manual | Continuous (agent) |
| **Cross-platform resolution** | **Per-package manager mapping** | N/A | Nix-only | Per-task conditionals | Per-OS Hiera data |
| **Shareable modules** | **First-class** | Templates only | Flakes | Roles (Galaxy) | Forge (server-oriented) |
| **Team config** | **Policy tiers + Crossplane** | N/A | Flake inputs | N/A | Puppet Enterprise |
| **Infrastructure** | **Single binary, zero servers** | Single binary | Nix daemon | SSH (or AWX) | PuppetServer + PuppetDB + CA |
| **Learning curve** | YAML + CLI | Go templates | Nix language | YAML + Jinja2 | Puppet DSL (Ruby) |
Puppet is the closest philosophical match: declarative state, continuous enforcement, module ecosystem. If that model clicked for you but standing up a JVM server and writing a Ruby-era DSL to manage your dotfiles in 2026 doesn't, `cfgd` is what that idea looks like rebuilt from scratch for developer workstations.
`cfgd` is a good fit when you want: one-liners for cross-platform machine bootstrapping, shareable dev environment modules, continuous reconciliation between machines or subscribed sources, or team config distribution with policy enforcement.
## Features
**For developers:**
- [One-command bootstrap](https://github.com/tj-smith47/cfgd/blob/HEAD/docs/bootstrap.md): `cfgd init --from