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-dev

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 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"

assertions:
  - name: "Cargo is available"
    check:
      type: command_exists
      command: cargo

🔧 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

⚙️ 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