GENV

Get Started

A thin layer over the package managers you already use. Desired state lives in one git-friendly genv.json. Run genv apply and the machine matches the spec.

Features

Targets & Package Managers

WSL2 does not inherit native arch. Put shared bits in defaults; use targets.ubuntu or targets.wsl-arch for distro-specific packages.

Quick Start

# One machine
genv init
genv add git
genv add neovim --version "0.10.*"
genv scan
genv status
genv apply --dry-run
genv apply --yes

# Multiple machines (schema v8)
genv migrate --write
genv map --target arch
genv export --target ubuntu --out ./u
genv apply --target ubuntu --dry-run
genv apply --target ubuntu --yes

Active target resolution: --target → $GENV_TARGET → host classification. Spec default is ~/.config/genv/genv.json; the lock is machine-local.

CLI Reference

• --file <path>: spec path (default under ~/.config/genv/)
• --lock-file <path>: lock path (default genv.lock.json)
• --target <id>: v8 target for apply / status / upgrade / mutate / export / map / scan
• --json: machine-readable envelope on stdout

Spec Format (schema v8 / v9 / v10)

{
  "schemaVersion": "8",
  "defaults": {
    "env": {
      "EDITOR": { "value": "nvim" }
    },
    "shell": {
      "aliases": {
        "ll": { "value": "ls -lah" }
      }
    }
  },
  "targets": {
    "macos": {
      "packages": [
        { "id": "git", "prefer": "brew" },
        { "id": "ripgrep", "prefer": "brew" }
      ]
    },
    "ubuntu": {
      "packages": [
        { "id": "git", "prefer": "apt" }
      ],
      "env": {
        "EDITOR": null
      }
    },
    "windows": {
      "packages": [
        {
          "id": "git",
          "prefer": "winget",
          "managers": { "winget": "Git.Git", "scoop": "git", "choco": "git" }
        }
      ]
    }
  },
  "updates": {
    "enabled": true,
    "interval": "24h",
    "autoApply": false,
    "notify": true
  },
  "repo": {
    "url": "https://github.com/example/dotfiles",
    "ref": "main"
  }
}

• Desired state lives under defaults and/or targets.<id>, not as top-level packages / env.
• No per-record host in v8/v9 (use target buckets).
• Target map entries may be null tombstones to drop a default for one OS.
• repo, updates, and v8 adapters stay top-level. Prefer v8 unless a managed external recipe requires v9.
• Schema v8 adapters declare plugin CLIs. Details are in SCHEMA.md.
• Schema v9 managed external releases: docs/external-releases.md and SCHEMA.md.
• Legacy v1-v7 specs still load. Convert with genv migrate.

Schema v10 adds local modules. genv.json registers module files by name under modules, and each target selects them with useModules:

{
  "schemaVersion": "10",
  "modules": {
    "base": "modules/base.json",
    "dev": "modules/dev.json"
  },
  "targets": {
    "macos": {
      "useModules": ["dev"],
      "packages": [{ "id": "ghostty" }]
    }
  }
}

// modules/base.json
{
  "schemaVersion": "10",
  "defaults": {
    "packages": [{ "id": "jq" }],
    "env": { "EDITOR": { "value": "nvim" } }
  }
}

// modules/dev.json
{
  "schemaVersion": "10",
  "requiresModules": ["base"],
  "defaults": { "packages": [{ "id": "ripgrep" }] }
}

• Modules are local, trusted files. Paths resolve inside the spec's directory; a module that escapes it is refused.
• useModules is additive: selecting dev also selects base through requiresModules. Here macOS gets ghostty, ripgrep, jq, and EDITOR.
• There is no override syntax. An identical declaration in the root and a module is kept once; a conflicting one is an error naming both origins.
• Module-owned resources are read-only from the CLI. Inspect a composition with genv config --target macos. genv migrate refuses v10. Details in SCHEMA.md.

How Apply and Locks Work

v8 merges defaults with the active target (including tombstones), then reconciles packages, env, shell, files, services, and hooks.

Roadmap

The v3 line closed the old milestone backlog. v4 is schema v8 multi-target configs plus schema v9 managed external releases, and schema v10 adds local modules and dependency-aware services. Future work lives in GitHub issues and ROADMAP.md.