Use

Configuration

One TOML file says what steward indexes and how. It is yours to edit, and steward edits it too (keeping your comments) when you change roots from the desktop app or the API.

Where it lives

~/.config/steward/settings.toml, or $XDG_CONFIG_HOME/steward/settings.toml. Set STEWARD_CONFIG to use another file. A missing file is fine: steward then indexes your home directory with default settings.

Unknown keys are errors, so a typo is reported instead of silently ignored.

Applying changes

After editing the file, any of these applies it without restarting:

steward reload                       # or:
systemctl --user reload steward      # the service maps reload to SIGHUP

A reload starts scanning new roots, rescans roots whose settings changed, and removes roots you deleted from the index (the files themselves are untouched, of course). The reload result lists what was added, changed and removed.

The desktop app’s Settings tab, steward put-root / steward remove-root, and the put_root / remove_root API methods validate the change, write it into this file with your comments and formatting kept, and apply it at once.

Top-level keys

key	default	meaning
`db`	`~/.local/state/steward/index.db`	The index file. `~` is expanded; `$XDG_STATE_HOME` moves the default.
`hash_threads`	half the CPUs, at most 4	Files hashed at once for content ids. Hashing is mostly disk-bound, and a few sequential readers beat many seeking ones on spinning disks. A change applies to the next hashing job.
`[[root]]`	your home directory	One table per root, below. With no `[[root]]` at all, steward indexes `$HOME`; `root = []` means no roots.

Root keys

key	default	meaning
`path`	required	The directory to index: absolute, or starting with `~`.
`interval_minutes`	`1440` (a day)	Time between scheduled rescans. At least 1.
`full_every`	`1`	Every Nth scheduled rescan is full; the rest are trusting. `0` and `1` both mean always full. See Staying current.
`one_filesystem`	`true`	Don’t descend into other filesystems mounted below `path`.
`exclude`	`[]`	Paths not to index at all, as gitignore patterns relative to `path`.
`classify`	`true`	Tag repositories, ignored files, build output, caches and the like.
`contentid`	`[]`	Folders whose files get content ids automatically, relative to `path` or absolute (inside the root).

Exclude patterns

exclude uses .gitignore syntax, anchored at the root’s path:

exclude = [
  "/Downloads/incomplete",   # leading slash: this exact path under the root
  "*.iso",                   # any file or directory with this name, anywhere
  "node_modules/",           # trailing slash: directories only
  "!/keep/node_modules/",    # negation re-includes
]

Excluded paths are not scanned, not counted in totals and never hashed.

Content id folders

Hashing reads every byte, so choose the folders where content identity is useful (a media library, downloads, photo archives) rather than all of your home directory:

[[root]]
path = "/home/media"
classify = false
contentid = ["Movies", "TV", "/home/media/Music"]

After each scan of the root, files in these folders without a current content id are queued for hashing. Files elsewhere get one only when an application or the command line asks (inspect, cid, hash).

A complete example

# ~/.config/steward/settings.toml

hash_threads = 2

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

[[root]]
path = "/home/media"
interval_minutes = 720          # twice a day
classify = false
contentid = ["Movies", "TV"]

[[root]]
path = "/mnt/archive"           # an external disk; offline when unplugged
contentid = ["/mnt/archive"]    # everything on it

Environment

variable	used by	meaning
`STEWARD_CONFIG`	daemon, CLI	Path of the settings file.
`XDG_CONFIG_HOME`	daemon, CLI	Base for the default settings path.
`XDG_STATE_HOME`	daemon	Base for the default index path.
`XDG_RUNTIME_DIR`	everything	Where the sockets live (`$XDG_RUNTIME_DIR/steward/`). Without it, a private directory under `/tmp`.
`STEWARD_DB`	CLI	Work directly on this index file instead of through the daemon (same as `--db`).
`RUST_LOG`	everything	Override log filtering, e.g. `RUST_LOG=steward_index=trace`. See Operations.