Installation

Installation

warden needs Python 3.11 or newer. Everything below uses uv, which brings its own Python if the machine has none.

Install it

uv tool install warden-ports
warden --version

If you see a version, it works.

The distribution is called warden-ports because warden on PyPI belongs to an unrelated project. The command it installs is warden either way, and so is the name you import in Python.

System	Where the command lands
Windows	%USERPROFILE%\.local\bin\warden.exe
Linux, macOS	~/.local/bin/warden

If the shell cannot find it afterwards, uv will have said which directory to add to PATH; uv tool update-shell does it for you on most shells.

Shell completion

warden --install-completion

Restart the shell afterwards. Command names, sub-commands and flags then complete on tab, in bash, zsh, fish and PowerShell. --show-completion prints the script instead of installing it, for a shell configuration kept in version control.

Starting it with the machine

warden service install

It prints the unit, agent or startup command it would write, asks once, and writes it. warden service status says whether it took, warden service uninstall takes it away again. See Command line.

Without installing anything

uvx --from warden-ports warden ports

Enough to look at a machine you would rather not install anything on.

From a checkout

To work on warden itself:

git clone https://github.com/vxnsin/warden
cd warden
uv sync
uv run warden
uv tool install .     # to put your own copy behind the `warden` command

Upgrading

uv tool upgrade warden-ports

Or let warden tell you when there is something to upgrade to, and fetch it across a whole fleet at once — see Updates.

The registry database survives upgrades. A schema change adds what it needs when the database is next opened, so nothing has to be thrown away.

Removing it

uv tool uninstall warden-ports

The database is not removed with it. Delete it by hand if you want it gone:

System	Path
Windows	%LOCALAPPDATA%\warden\registry.db
Linux	~/.local/share/warden/registry.db
macOS	~/Library/Application Support/warden/registry.db