CLI
All dither subcommands at a glance.
The dither binary is the only entry point in v0. It wraps a small set of subcommands built with citty.
dither --helpSubcommands
| Command | What it does |
|---|---|
dither init | Required first step: write config, set library path, prefetch weights. |
dither search <query> | Search across entries (hybrid by default, --mode lex for BM25-only). |
dither get <ref> | Print the body of an entry by display path or docid. |
dither index update | Re-scan the library and refresh the qmd index. |
dither plugin install <path> | Install a plugin from a local directory. |
dither plugin run <target> | Run a plugin once, by name or path, with optional per-run overrides. |
dither plugin list | List installed plugins. |
dither plugin remove <name> | Uninstall a plugin (deletes code, state, grants). |
dither collection add/list/remove | Register a pre-existing folder as an external collection alongside library subdirs. |
dither env set/get/unset/list | Manage the dither global env store at <dither-home>/env.json. |
dither runs list/tail | Inspect the persistent run journal under <dither-home>/history/. |
dither daemon start/stop/status/reload | Manage the background daemon that schedules plugin runs and watches files. |
dither status | Print where dither is installed, library health, and daemon state. |
Library-needing commands refuse with a clear error until dither init has run. Today that gate is enforced on search, get, index update, plugin install, plugin run, daemon start, and collection add/list/remove. Everything else (env, plugin list, plugin remove, runs, daemon status/stop/reload, status, init itself) works without init.
Exit codes
The CLI does not yet enforce a documented exit code contract. Today, citty surfaces a non-zero exit on any thrown error and zero on success. A few commands set specific exit codes — dither env get/unset exit 1 on "no such env", dither init exits 2 when --library is required but missing on a non-TTY, dither daemon stop exits 1 on timeout — but don't script around the full set.
Output format
Most commands print plain tab- or space-separated lines on stdout, suited to piping through awk, cut, or fzf. dither status and dither daemon status accept --json for structured output.