Anvil

Declarative Workstation Configuration Management

Anvil is a declarative configuration management tool for developer workstations. Define your development environment in YAML, and Anvil will install packages, copy configuration files, run setup scripts, and verify system health. Currently supports Windows (winget), with cross-platform support planned.

✨ Features

• 📦 Package Management - Install software via winget with version pinning
• 📁 File Synchronization - Copy configuration files with automatic backup
• 🔧 Script Execution - Run PowerShell setup and validation scripts
• 🧬 Workload Inheritance - Compose configurations using DRY principles
• ✅ Health Checks - Validate system state matches workload definition
• 🔍 Assertions & Conditions - Declarative system state predicates for health validation
• 📊 Multiple Formats - Output as table, JSON, YAML, or HTML reports
• 🔄 Backup & Restore - Save and restore system state
• 🐚 Shell Completions - Tab completion for PowerShell, Bash, Zsh, Fish
• 🌐 Multi-Platform Design - Windows support now; macOS and Linux on the roadmap

🚀 Quick Start

Installation

Option 1: Install from crates.io

# Prerequisites: Rust 1.75+
cargo install anvil-cli

Option 2: Download from Releases

# Download latest release
Invoke-WebRequest -Uri "https://github.com/kafkade/anvil/releases/latest/download/anvil-windows-x64.zip" -OutFile anvil.zip
Expand-Archive anvil.zip -DestinationPath C:\Tools\anvil
$env:PATH += ";C:\Tools\anvil"

Option 3: Build from Source

# Prerequisites: Rust 1.75+
git clone https://github.com/kafkade/anvil.git
cd anvil
cargo build --release
# Binary is at target/release/anvil.exe

Basic Usage

# List available workloads
anvil list

# Preview what would happen
anvil install rust-developer --dry-run

# Install a workload
anvil install rust-developer

# Check system health
anvil health rust-developer

# Generate HTML health report
anvil health rust-developer --output html --file report.html

📦 Bundled Workloads

Workload	Description
essentials	Core development tools (VS Code, Git, Windows Terminal) and productivity utilities
rust-developer	Rust toolchain with cargo tools (extends essentials)
python-developer	Python 3.12 with uv package manager (extends essentials)

📋 Workload Structure

A workload is a configuration bundle:

my-workload/
├── workload.yaml       # Workload definition
├── files/              # Configuration files to deploy
└── scripts/            # Installation and health scripts

Example Workload

name: rust-developer
version: "1.0.0"
description: "Complete Rust development environment"

extends:
  - essentials

packages:
  winget:
    - id: Rustlang.Rustup
    - id: LLVM.LLVM

files:
  - source: config.toml
    destination: "~/.cargo/config.toml"
    backup: true

scripts:
  post_install:
    - path: scripts/setup.ps1
      description: "Install Rust components"
      
  health_check:
    - path: scripts/health.ps1
      name: "Rust Toolchain"

🔧 CLI Reference

anvil <COMMAND>

Commands:
  install      Apply a workload configuration
  health       Validate system against workload
  list         List available workloads
  show         Display workload details
  validate     Validate workload syntax
  init         Create new workload template
  status       Show installation status
  backup       Manage file backups
  config       Manage global configuration
  completions  Generate shell completions

Global Options:
  -v, --verbose    Increase verbosity (-v, -vv, -vvv)
  -q, --quiet      Suppress output
  -c, --config     Use custom configuration file
      --no-color   Disable colored output
  -h, --help       Show help
  -V, --version    Show version

📚 Documentation

Document	Description
User Guide	Complete usage instructions
Workload Authoring	Creating custom workloads
Troubleshooting	Common issues and solutions
Specification	Technical spec and roadmap
Architecture	Internal code architecture
Contributing	Contribution guidelines
Changelog	Version history

⚙️ Requirements

Current platform support: Windows

• Windows 10 (version 1809+) or Windows 11
• Windows Package Manager (winget)
• PowerShell 5.1 or later

Cross-platform support (macOS via Homebrew, Linux via APT) is on the roadmap.

🛠️ Building from Source

Prerequisites

• Rust 1.75 or later
• Visual Studio Build Tools (for Windows linking)

Build

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with verbose output
cargo run -- -vvv list

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Creating workloads

📄 License

This project is dual-licensed under MIT and Apache-2.0.

🙏 Acknowledgments

• winget - Windows Package Manager
• clap - Command line argument parser
• serde - Serialization framework
• handlebars - Template engine

---

Made with ❤️ for developers