{
  "markdown": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/tj-smith47/cfgd/master/.github/gear.svg\" width=\"96\" alt=\"cfgd gear icon\">\n\n# cfgd\n\nDeclare your entire machine (packages, dotfiles, system settings, secrets) with composable profiles and shareable, cross-platform modules.\n\n[![CI](https://github.com/tj-smith47/cfgd/actions/workflows/ci.yml/badge.svg)](https://github.com/tj-smith47/cfgd/actions/workflows/ci.yml)\n[![E2E](https://github.com/tj-smith47/cfgd/actions/workflows/e2e.yml/badge.svg)](https://github.com/tj-smith47/cfgd/actions/workflows/e2e.yml)\n[![Release](https://github.com/tj-smith47/cfgd/actions/workflows/release.yml/badge.svg)](https://github.com/tj-smith47/cfgd/actions/workflows/release.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/tj-smith47/cfgd/badges/coverage.json)](https://github.com/tj-smith47/cfgd/actions/workflows/ci.yml)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](#license)\n\n<img src=\"demo/cfgd-demo.gif\" width=\"1320\" alt=\"cfgd installing a Neovim setup on a bare Ubuntu container in one command\">\n\n*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).*\n\n</div>\n\n> **Status:** Alpha. APIs may change.\n\n---\n\n- [What is cfgd](#what-is-cfgd)\n- [How It Works](#how-it-works)\n- [Quick Start](#quick-start)\n- [Why cfgd exists](#why-cfgd-exists)\n- [Shareable Modules](#shareable-modules)\n- [How cfgd compares](#how-cfgd-compares)\n- [Features](#features)\n- [Documentation](#documentation)\n- [Distribution](#distribution)\n\n---\n\n## What is cfgd\n\nMost dotfile managers track files. `cfgd` enables you to manage 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's detected and corrected.\n\n## How It Works\n\n**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](docs/profiles.md).\n\n```\n             base\n            ╱    ╲\n        work    personal\n       ╱    ╲\n  laptop    devcontainer\n```\n\n**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](docs/modules.md).\n\n**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](docs/reconciliation.md).\n\n## Quick Start\n\n```sh\n# Install via Homebrew\nbrew install tj-smith47/tap/cfgd\n\n# Or via install script\ncurl -fsSL https://github.com/tj-smith47/cfgd/releases/latest/download/install.sh | sh\n\n# Or via cargo\ncargo install cfgd\n\n# Bring your config to a new machine in seconds\ncfgd init --from git@github.com:you/machine-config.git\n\n# Or start fresh\ncfgd init\n\n# Or let AI scan your system and generate config for you\nexport ANTHROPIC_API_KEY=sk-...\ncfgd generate\n\n# Set up shell completions (add to your shell's rc file)\nsource <(cfgd completion bash)  # .bashrc\nsource <(cfgd completion zsh)   # .zshrc\ncfgd completion fish | source   # config.fish\n```\n\n## Why cfgd exists\n\nI 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 gradually discovered things I'd forgotten, as well as some things (e.g., System Settings) that I thought would have been nice to have included in the backup. This all felt very manual and incomplete, and I thought there needed to be a better way; I should just be able to clone a repo and have my entire workstation (packages, scripts, dotfiles, system settings) feel familiar again. And even better, to keep aspects of that feeling in sync between my home and work laptops (parts of it, at least).\n\nAnother inspiring aspect had to do with working in 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 inside the container once they shell in. At minimum, I wanted my full neovim editor setup available in any ephemeral container without having to modify the devcontainer config in every team's repository I worked in just to accommodate my setup. I needed something that could bootstrap my config into any environment from the outside, regardless of which / 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 and easy way to share my exact setup, down to the alias.\n\n`cfgd` borrows from the best ideas across practices:\n\n- **Kubernetes**: declarative reconciliation loop, KRM resource model\n- **Terraform**: plan/apply workflow, state tracking, drift detection\n- **Puppet**: continuous enforcement via daemon, module ecosystem\n- **Nix**: reproducible machine state from a single source of truth\n- **Ansible**: YAML-driven config management, idempotent task execution\n- **Kustomize**: layered overrides and patches\n- **chezmoi**: dotfile management\n\n## Shareable Modules\n\nThis is my favorite feature: a single packaged config for a tool that works anywhere.\n\n```sh\ncfgd module create my-dev-env\ncfgd profile update --module community/nvim\n```\n\nA module declares packages with cross-platform resolution, config files, shell environment variables and aliases, and lifecycle scripts:\n\n```yaml\napiVersion: cfgd.io/v1alpha1\nkind: Module\nmetadata:\n  name: nvim\n  description: Neovim editor configuration\nspec:\n  depends: [node, python]\n  packages:\n    - name: neovim\n      minVersion: \"0.10\"\n      prefer: [brew, snap]\n      deny: [apt]\n    - name: ripgrep\n    - name: fd\n      aliases:\n        apt: fd-find\n        dnf: fd-find\n    - name: gcc\n      aliases:\n        apt: build-essential\n        dnf: \"@development-tools\"\n      platforms: [linux]\n  files:\n    - source: files/init.lua\n      target: ~/.config/nvim/init.lua\n    - source: files/lua\n      target: ~/.config/nvim/lua\n  env:\n    - name: EDITOR\n      value: nvim\n  aliases:\n    - name: v\n      command: nvim\n  scripts:\n    postApply:\n      - nvim --headless '+Lazy! sync' '+MasonToolsInstallSync' +qa\n```\n\nSee [docs/modules.md](docs/modules.md) for the full spec including git file sources, registries, and dependency resolution.\n\n## How cfgd compares\n\n| | **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/) |\n|---|---|---|---|---|---|\n| **Focus** | Full machine state | Dotfiles | Dotfiles + packages (Nix) | General automation | Server/infra state |\n| **Packages** | **18 managers** | None | Nix only | Any (via tasks) | Any (via providers) |\n| **Drift detection** | **Continuous (daemon)** | Manual | On rebuild | Manual | Continuous (agent) |\n| **Cross-platform resolution** | **Per-package manager mapping** | N/A | Nix-only | Per-task conditionals | Per-OS Hiera data |\n| **Shareable modules** | **First-class** | Templates only | Flakes | Roles (Galaxy) | Forge (server-oriented) |\n| **Team config** | **Policy tiers + Crossplane** | N/A | Flake inputs | N/A | Puppet Enterprise |\n| **Infrastructure** | **Single binary, zero servers** | Single binary | Nix daemon | SSH (or AWX) | PuppetServer + PuppetDB + CA |\n| **Learning curve** | YAML + CLI | Go templates | Nix language | YAML + Jinja2 | Puppet DSL (Ruby) |\n\nPuppet 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.\n\n`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.\n\n## Features\n\n**For developers:**\n- [One-command bootstrap](docs/bootstrap.md): `cfgd init --from <repo> --apply` on a new machine\n- [AI-guided generation](docs/ai-generate.md): `cfgd generate` scans your system and builds profiles/modules; MCP server for AI editor integration\n- [MCP server](docs/ai-generate.md#serving-the-cli-itself): `cfgd mcp` serves the CLI itself as tools, so an assistant can reconcile a machine, not just write config for one\n- [Authoring skills](docs/skill.md): `cfgd skill install` teaches your coding agent (Claude Code, Gemini, Copilot, Codex, Cursor) to author high-quality cfgd resources\n- [Shareable modules](docs/modules.md): cross-platform dev environment packages with dependency resolution and registries\n- [18 package managers](docs/packages.md): brew, apt, dnf, pacman, cargo, npm, pipx, snap, and more, with automatic platform-aware resolution\n- [Secrets](docs/secrets.md): SOPS/age encryption + 1Password, Bitwarden, HashiCorp Vault; secret-backed environment variables\n- [Tera templates](docs/templates.md): render dotfiles with variables, OS detection, custom functions\n- [Continuous drift detection](docs/daemon.md): daemon watches for changes, auto-syncs, notifies or auto-corrects\n\n**For platform & infrastructure engineers:**\n- [Multi-source config](docs/sources.md): publish team baselines with policy tiers (locked/required/recommended/optional)\n- [Kubernetes operator](docs/operator.md): CRDs for MachineConfig, ConfigPolicy, DriftAlert; admission webhook; device gateway with fleet dashboard\n- [Node configuration](docs/system-configurators.md): sysctl, kernel modules, containerd, kubelet, AppArmor, seccomp, certificates\n- [CSI driver](docs/operator.md): OCI-based module injection into pods via volumes\n- [Crossplane integration](docs/team-config.md): TeamConfig XR for self-service team environment distribution\n- [kubectl plugin](docs/operator.md): `kubectl cfgd debug/exec/inject/status` for node inspection\n\n**For security & compliance:**\n- [Compliance snapshots](docs/spec/config.md#speccompliance): continuous machine state capture with JSON/YAML export for Vanta, Drata, or custom integrations\n- [Key provisioning](docs/system-configurators.md): declarative SSH key generation, GPG key management, and git signing configuration\n- [Encryption enforcement](docs/spec/profile.md): per-file encryption requirements with SOPS/age backend validation\n- [Policy enforcement](docs/sources.md): locked files, required packages, encryption constraints on target paths\n- [Drift remediation](docs/daemon.md): daemon detects and auto-corrects configuration drift with per-module policies\n- [Fleet visibility](docs/operator.md): device gateway aggregates compliance scores across enrolled machines\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [Configuration](docs/configuration.md) | Root config (cfgd.yaml), file strategies, aliases, themes |\n| [Profiles](docs/profiles.md) | Profile YAML, inheritance, merge rules, variables |\n| [Modules](docs/modules.md) | Module spec, cross-platform packages, dependencies, git file sources, registries |\n| [Reconciliation](docs/reconciliation.md) | Phase ordering, failure handling, state store |\n| [Packages](docs/packages.md) | All package managers, skip behavior, dry-run |\n| [Templates](docs/templates.md) | Tera template system, context variables, custom functions |\n| [Secrets](docs/secrets.md) | SOPS/age backends, 1Password, Bitwarden, Vault |\n| [System Configurators](docs/system-configurators.md) | Shell, macOS defaults, systemd, sysctl, kubelet, and more |\n| [Sources](docs/sources.md) | Multi-source config, policy tiers, composition, subscriptions |\n| [Daemon](docs/daemon.md) | File watching, reconciliation loop, sync, notifications, service install |\n| [Operator](docs/operator.md) | CRD-based machine management, device gateway, DaemonSet node agent |\n| [Team Config](docs/team-config.md) | Crossplane-powered team config distribution |\n| [Safety](docs/safety.md) | Atomic writes, backups, rollback, apply locking, path safety |\n| [Declarative Backups](docs/backups.md) | `spec.backups[]` snapshots, hook ordering, retention, restoring |\n| [CLI Reference](docs/cli-reference.md) | Complete command reference with flags and examples |\n| [Installation](docs/installation.md) | All install channels (Homebrew, install script, winget, scoop, chocolatey, cargo, direct download) |\n| [Bootstrap](docs/bootstrap.md) | `cfgd init` flow, apply options, install script |\n| [AI Generate](docs/ai-generate.md) | AI-guided config generation, both MCP servers (`mcp-server` for authoring, `mcp` for driving the CLI) |\n| [Authoring Skills](docs/skill.md) | `cfgd skill` installer, supported agent providers, choosing between generate and skills |\n| [Releasing](docs/releasing.md) | CI-cut release pipeline, pre-release checklist, failure recovery |\n| [Image Pack](docs/image-pack.md) | Packing a directory into an OCI image volume, signing, pinning deployments |\n| [Multi-Tenancy](docs/multi-tenancy.md) | Namespace isolation and tenant boundaries for the operator |\n| [Lifecycle Scripts](docs/lifecycle-scripts.md) | `run:` resolution, hook phases, timeouts, interactive scripts |\n\n## Distribution\n\nIn addition to publishing binaries to [GitHub Releases](https://github.com/tj-smith47/cfgd/releases) (Linux, macOS, Windows; amd64 + arm64), each release also publishes to:\n\n| Channel | Artifact |\n|---|---|\n| [Homebrew](https://github.com/tj-smith47/homebrew-tap) | `brew install tj-smith47/tap/cfgd` |\n| [crates.io](https://crates.io/crates/cfgd) | `cargo install cfgd` |\n| [AUR](https://aur.archlinux.org/packages/cfgd) | `yay -S cfgd` (Arch Linux; builds from source) |\n| [GHCR](https://ghcr.io/tj-smith47) | Docker images: `cfgd`, `cfgd-operator`, `cfgd-csi` |\n| [Helm](chart/cfgd/) | `helm install cfgd oci://ghcr.io/tj-smith47/charts/cfgd` |\n| [Krew](manifests/krew/) | `kubectl krew install cfgd` (the [kubectl plugin](docs/operator.md) for node debugging and fleet inspection) |\n| [OLM](ecosystem/olm/) | Operator bundle for OLM-managed clusters |\n| [Crossplane](function-cfgd/) | `function-cfgd` composition function for [team config distribution](docs/team-config.md) |\n\n**CI/CD integrations:**\n\n| Integration | Description |\n|---|---|\n| [cfgd Setup](ecosystem/github-actions/setup/) | GitHub Action: bootstrap a runner with a module from your config repo |\n| [cfgd Plan](ecosystem/github-actions/plan/) | GitHub Action: run `cfgd plan` on PRs, post the diff as a comment |\n| [GitLab CI](ecosystem/gitlab/) | Includable `.cfgd-ci.yml` template with `.cfgd-plan` and `.cfgd-apply` jobs |\n| [Tekton](ecosystem/tekton/) | `cfgd-apply` Task for Tekton Pipelines |\n\n```yaml\n# Example: set up your dev tools on a GitHub Actions runner\n- uses: tj-smith47/cfgd/ecosystem/github-action-setup@master\n  with:\n    source: git@github.com:you/machine-config.git\n    module: dev-tools\n```\n\nModules can also be exported as [DevContainer Features](https://containers.dev/implementors/features/) for injection into devcontainers:\n\n```sh\ncfgd module export my-tool --format devcontainer\n```\n\n**Building from source:**\n\n```sh\ngit clone https://github.com/tj-smith47/cfgd.git && cd cfgd\ncargo build --release\n```\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n",
  "bytes": 16171,
  "sha": "9a7e1f4ff2654158202f4d94d4cab50bad76f241afc1cf2ad22143d7cfcb0dbc",
  "repo_slug": "tj-smith47/cfgd",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tj_smith47_cfgd_d6591802/readme"
}