Warden

Describe the system you live in

Warden captures your development environment — git identities, SSH configs, system packages, and developer tools — into a single JSON5 config file. Switch identities, snapshot installed software, apply configs to a fresh machine, back everything up into portable archives, and keep your system clean.

Identity — switch git identity (name, email, signing key, SSH command) in one step
Packages — scan, install, and apply across 14 package managers
Backup — portable .tar.gz archives with module selection and smart merge on restore
Maintenance — system cleanup and optimization via Mole (macOS) — we love it
China mirrors — WARDEN_USE_CN=1 routes all downloads through CN-accessible mirrors

Quick Start

One-line install:

curl -fsSL https://raw.githubusercontent.com/LBYPatrick/warden/main/scripts/remote-install.sh | bash

Or clone manually:

git clone https://github.com/LBYPatrick/warden.git ~/.warden/repo
cd ~/.warden/repo
make install

Then:

warden pkg scan                    # snapshot system packages into config
warden id switch personal          # apply a git identity
warden pkg apply                   # install missing packages from config
warden backup -o ~/backup.tar.gz   # backup everything
warden restore ~/backup.tar.gz     # restore on a new machine

Prerequisites

Requirement	Version	Notes
Python	3.13+	Runtime
uv	latest	Auto-installed by `make install` if missing

Config

Warden searches for warden.jsonc in this order (first found wins):

~/.warden/warden.jsonc
~/.ssh/warden.jsonc
~/warden.jsonc
./warden.jsonc

Or pass -c <path> for an explicit file.

{
  "identities": {
    "personal": {
      "name": "Your Name",
      "email": "you@example.com",
      "signing_key": "~/.ssh/id_ed25519.pub",
    },
  },
  // Populated by `warden pkg scan`
  "packages": {
    "brew": { "formulae": ["git", "ripgrep"], "casks": ["firefox"] },
    "cargo": { "packages": ["bat", "fd-find"] },
    "npm": { "packages": ["typescript"] },
  },
  "tools": ["rustup", "node", "pnpm"]
}

Legacy flat format (identities at root level) is still supported for reads.

Usage

Identity (`warden id`)

warden id switch <target>    # apply git identity (case-insensitive)
warden id list               # list all targets
warden id show               # show current git identity
warden id show <target>      # show a specific target

Each switch configures user.name, user.email, user.signingkey, core.sshCommand, gpg.format=ssh, and commit.gpgsign=true.

Packages (`warden pkg`)

warden pkg scan              # scan system → update packages/tools in config
warden pkg apply             # install missing packages from config
warden pkg apply --force     # reinstall everything
warden pkg install MGR:PKG   # install via any manager

pkg install uses manager:package syntax:

warden pkg install brew:ripgrep cask:firefox cargo:bat
warden pkg install --save brew:fd     # also adds to warden.jsonc
warden pkg install --any apt:curl     # bypass OS platform check

Supported package managers (14)

Manager	Platform	Config key
`brew`	macOS, Linux	`packages.brew.formulae`
`cask`	macOS, Linux	`packages.brew.casks`
`mas`	macOS	`packages.mas.apps`
`apt`	Linux	`packages.apt.packages`
`dnf`	Linux	`packages.dnf.packages`
`pacman`	Linux	`packages.pacman.packages`
`apk`	Linux	`packages.apk.packages`
`snap`	Linux	`packages.snap.packages`
`flatpak`	Linux	`packages.flatpak.packages`
`cargo`	both	`packages.cargo.packages`
`npm`	both	`packages.npm.packages`
`pnpm`	both	`packages.pnpm.packages`
`pipx`	both	`packages.pipx.packages`
`tool`	both	`tools` (dev tool slugs)

Backup & Restore

Use -m to select which modules to backup or restore. Backup defaults to all. Restore auto-detects modules from the archive when -m is omitted.

Module	What it includes
`git`	Identities + signing keys
`ssh`	`~/.ssh/config` + identity keys
`pkg`	Packages + tools from config + apt sources (Linux)

warden backup                         # backup everything (scans packages first)
warden backup -m git                  # just identities + keys
warden backup -m git,ssh              # identities + SSH config
warden backup --skip-scan             # skip package re-scan
warden backup -o ~/bak.tar.gz         # custom output path

warden restore ~/backup.tar.gz        # auto-detect and restore available modules
warden restore -m git ~/backup.tar.gz # restore just identities
warden restore -m pkg ~/backup.tar.gz # restore just packages
warden restore -m all ~/backup.tar.gz # explicitly restore all modules

Restore auto-detects available modules from the archive marker when -m is not specified. Use -m to override. Merge on restore: identities override by name; package lists union-merged (sorted, deduplicated); SSH hosts updated by name, new ones appended. On Linux, apt sources are backed up and restored with the pkg module.

Linux improvements: APT scanning captures only user-installed packages (via apt-mark showmanual), not auto-installed dependencies. APT install filters packages through apt-cache to skip unavailable ones, then installs all available packages in a single apt-get call.

Maintenance (`warden mole`) — macOS only

System cleanup and optimization powered by Mole — we love it. Auto-installed via Homebrew if not already present.

warden mole clean              # deep system cleanup (caches, logs, temp files)
warden mole optimize           # rebuild system databases and services
warden mole analyze            # visual disk space explorer
warden mole analyze /Volumes   # analyze a specific path
warden mole status             # real-time system health dashboard
warden mole status --json      # machine-readable JSON output

For additional features, run mo directly:

mo                             # interactive menu
mo uninstall                   # smart app uninstaller
mo purge                       # clean build artifacts (node_modules, target, etc.)
mo installer                   # find and remove .dmg/.pkg/.zip installers
mo touchid                     # configure Touch ID for sudo

Self-Update

warden update                  # pull latest + reinstall
warden update main             # pull from a specific branch

Global Flags

Flag	Description
`-c PATH`	Override config file path
`--dry-run`	Preview changes without writing to disk
`--no-color`	Disable colored output (also: `WARDEN_NO_COLOR=1`)

Man Page

man warden

Installed automatically by make install.

China Mirror Mode

Set WARDEN_USE_CN=1 to route downloads through CN-accessible mirrors:

What	Mirror
Homebrew	USTC (`mirrors.ustc.edu.cn`)
PyPI / uv	Aliyun (`mirrors.aliyun.com`)
Rust (rustup)	rsproxy.cn
Node / npm / pnpm	npmmirror.com
GitHub downloads	ghp.ci proxy

Works with remote install too:

WARDEN_USE_CN=1 curl -fsSL https://raw.githubusercontent.com/LBYPatrick/warden/main/scripts/remote-install.sh | bash

Project Structure

warden/
  __main__.py       # argparse CLI — subcommand definitions and dispatch
  cli.py            # command implementations (id, pkg, update)
  config.py         # JSON5 config loading, resolution, merge algorithm
  display.py        # rich-powered output (respects WARDEN_NO_COLOR)
  backup.py         # backup/restore + archive marker logic
  mole.py           # Mole integration (system cleanup, macOS only)
  ssh_config.py     # SSH config parser, serializer, merge engine
  scanner.py        # multi-manager package scanning
  installer.py      # multi-manager package installation
  cn.py             # China mirror URL rewrites and env vars
  platform_info.py  # OS/arch detection
bin/warden          # bash wrapper (symlink-friendly)
man/                # man page (warden.1)
completions/        # bash + zsh tab-completion
tests/              # pytest suite
scripts/            # install, uninstall, remote-install, formatter setup

Development

Command	Description
`make install`	Install deps, symlink binary, man page, completions
`make uninstall`	Remove symlink, caches, man page, completions
`make test`	Run pytest suite
`make format`	Run ruff + beautysh
`make build`	Verify the CLI runs
`make clean`	Remove `.venv`, caches, build artifacts

Shell Completions

Installed automatically by make install. For manual setup:

Zsh

Add to ~/.zshrc:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Bash

Completions are installed to ~/.local/share/bash-completion/completions/warden.

Troubleshooting

warden: command not found

Run make install to symlink the binary to /usr/local/bin/warden. If /usr/local/bin is not on your PATH, add it or create a symlink manually.

Config not found

Warden searches ~/.warden/warden.jsonc, ~/.ssh/warden.jsonc, ~/warden.jsonc, then ./warden.jsonc. Use -c <path> to point to a specific file. Running warden pkg scan creates a new config at ~/.warden/warden.jsonc if none exists.

Module not found in archive on restore

Each archive records which modules it contains. Use warden backup (defaults to all) to create a full archive. To restore specific modules, pass -m git,pkg etc. — the error message shows which modules are available in the archive.

Legacy config format

If your warden.jsonc uses the old flat format (identities at root level), it still works for all identity commands. Run warden pkg scan to migrate to the new unified format.

License

LGPL-3.0-or-later

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github/workflows		.github/workflows
bin		bin
completions		completions
man		man
scripts		scripts
tests		tests
warden		warden
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
VERSION		VERSION
pyproject.toml		pyproject.toml
tidy.sh		tidy.sh
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Warden

Quick Start

Prerequisites

Config

Usage

Identity (`warden id`)

Packages (`warden pkg`)

Backup & Restore

Maintenance (`warden mole`) — macOS only

Self-Update

Global Flags

Man Page

China Mirror Mode

Project Structure

Development

Shell Completions

Troubleshooting

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Warden

Quick Start

Prerequisites

Config

Usage

Identity (warden id)

Packages (warden pkg)

Backup & Restore

Maintenance (warden mole) — macOS only

Self-Update

Global Flags

Man Page

China Mirror Mode

Project Structure

Development

Shell Completions

Troubleshooting

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Identity (`warden id`)

Packages (`warden pkg`)

Maintenance (`warden mole`) — macOS only

Packages