Start

Getting started

Build steward, run it as a user service, point it at your files and ask it some questions. Ten minutes, most of them spent waiting for the first scan.

Install

steward runs on Linux, on x86_64 and ARM64. Install the latest release into ~/.local/bin, without root:

curl -fsSL https://toppk.github.io/steward/install.sh | sh

The installer downloads the release for your machine, verifies its SHA-256 checksums, and installs:

It only ever replaces earlier steward builds, and never an unrelated program of the same name. It reports whether it installed, upgraded, or found the same version already there, and doesn’t change your shell configuration (it warns if ~/.local/bin isn’t on your PATH). Set STEWARD_INSTALL_DIR to install somewhere else.

To inspect first, read install.sh, or download directly from GitHub Releases. Each release has steward_linux_amd64, steward_linux_arm64, steward-ui_linux_amd64 and steward-ui_linux_arm64, each with a .sha256 file:

curl -fLO https://github.com/toppk/steward/releases/latest/download/steward_linux_amd64
curl -fLO https://github.com/toppk/steward/releases/latest/download/steward_linux_amd64.sha256
sha256sum -c steward_linux_amd64.sha256
install -m 755 steward_linux_amd64 ~/.local/bin/steward

Then run the daemon as a systemd user service, now and at every login:

steward service install
steward service logs -f      # watch it work

steward service install writes ~/.config/systemd/user/steward.service for the installed steward, enables it and starts it. The service runs at Nice=10 with idle I/O priority, so scans and hashing yield to everything else. To keep it running while you’re logged out, enable lingering (loginctl enable-linger).

Upgrading is steward upgrade: it installs the latest release the same way and restarts the service. steward version shows the version of both the command and the running daemon.

From source

You need Rust 1.97 or newer, just and, for the desktop app, the GPUI build dependencies (just deps installs them on Fedora). Then:

git clone https://github.com/toppk/steward
cd steward
just install        # builds, installs to ~/.local/bin, runs `steward service install`

To try it without installing, run just daemon -v in one terminal and just cli … in another.

Choose what to index

With no settings file, steward indexes your home directory. To choose, write ~/.config/steward/settings.toml. just init-config installs a fully commented example. A typical file:

[[root]]
path = "~"
exclude = ["/.cache/", "node_modules/"]

[[root]]
path = "/home/media"
classify = false                 # no git repositories to find here
contentid = ["Movies", "TV"]     # compute content ids for these folders

Each [[root]] is a directory tree with its own policy: how often to rescan, what to exclude, whether to classify, which folders get content ids. Apply changes with steward reload (or kill -HUP the daemon). The desktop app’s Settings tab edits the same file and applies it at once. Configuration lists every key.

Watch the first scan

The first scan of a root reads every directory under it. Ask for progress:

steward status          # JSON: roots, scan in progress, hashing, activity
steward settings        # each root's policy and index totals

or open the desktop app (steward-ui) and its Daemon tab. When a root has been scanned once, later rescans are quick: by default steward rescans each root once a day, and skips directories whose times show nothing changed inside them.

Ask some questions

steward tree ~ -d 2                  # where the space goes, two levels deep
steward ls ~/Downloads               # children, largest first
steward stat ~/src/steward           # one entry, with its tags
steward locate '*.iso'               # by name: glob, or substring without * ? [
steward locate invoice -l 20         # substring match, first 20

Every answer comes from the index, without touching the disk. stat shows tags such as classify:repo or classify:build-output, inherited from the directory that earned them.

Content ids

Folders listed under contentid are hashed in the background after each scan. Any file can also be hashed on demand:

steward inspect ~/Downloads/debian-13.iso
# [{ "path": "...", "kind": "file", "id": "btv2:5b1f…", "size": 702545920, "error": null }]

steward resolve btv2:5b1f…           # where is this content now?
steward dups /home/media             # identical files, most wasted space first
steward content-summary /home/media  # how much of it has content ids

A content id names the bytes, so it stays the same when the file is renamed or moved, even onto another disk. Concepts explains what it is and when it changes.

Without the daemon

Every steward command can also work directly on an index file, with no daemon involved, using --db PATH (or STEWARD_DB). This is handy for experiments and for one-off indexes:

steward --db /tmp/usr.db scan /usr
steward --db /tmp/usr.db tree /usr -d 1
steward --db /tmp/usr.db export-qdirstat /usr -o /tmp/usr.cache.gz

The last command writes a cache file that qdirstat opens directly.

Uninstall

steward service uninstall                       # stop, disable and remove the unit
rm ~/.local/bin/steward ~/.local/bin/steward-ui

Your settings (~/.config/steward/) and the index (~/.local/state/steward/) stay; delete them yourself if you want them gone.