dither init

dither init is the required first step before any library-needing command will run. It writes <dither-home>/config.json, creates the library directory, and pre-downloads qmd's model weights so the first dither search doesn't hang.

dither init
dither init --library ~/Documents/dither
dither init --no-download

Arguments

If you don't pass --library on a TTY, init drops into an interactive prompt for the path (default: <dither-home>/library). Without a TTY, --library is required and init exits with code 2 if it's missing.

What it does

1. Ensure <dither-home>/ exists.
2. If config.json already exists: print the current paths and exit 0. --library on a re-run is ignored with a note that re-init isn't supported.
3. Resolve the library path (flag or interactive prompt):
   • If the path doesn't exist, create it (with parents) and report created in the summary.
   • If the path exists and is a regular file, error out.
   • If the path exists and isn't writable, error out.
   • Resolve symlinks via realpath and store the canonical target in config.
4. Write <dither-home>/config.json (schema.version: 2, library.path, empty collections.external).
5. Run store.update() once over the library so the qmd SQLite exists with schema applied. Empty libraries skip this — the SQLite is created lazily on first plugin promote.
6. Unless --no-download, attempt to pre-download embedding/rerank model weights. Failure is non-fatal — the summary flags it and search degrades to lex-only until weights land.

Pre-init guardrail

Until init has run, every library-needing command refuses with:

error: dither is not initialized. Run `dither init` to set up your library.

Library-needing commands include search, get, index update, plugin install, plugin run, daemon start. Commands that don't touch the library (--help, --version, env, plugin list, plugin remove, runs, daemon status/stop/reload, status, init itself) keep working.

Where things land

After a successful init:

<dither-home>/config.json            ← schema + library.path
<dither-home>/qmd-index.sqlite       ← always in dither home, regardless of library
<library>/                           ← markdown lives here; collections are top-level subdirs

The qmd index always lives in dither home. If you point dither at a folder also indexed by qmd-CLI elsewhere, the two indices are independent.

Reconfiguring later

dither init is one-shot — re-running it on an already-initialised home is a read-only no-op. There is no --force. To change the library path, remove <dither-home>/config.json and run dither init again:

rm ~/.dither/config.json
dither init --library ~/Documents/dither

The old library directory is not moved or deleted — it stays on disk for you to handle. The qmd index also stays; drop qmd-index.sqlite if you want it rebuilt against the new library.

If the daemon is running, send it a reload after the reconfig so it picks up the new library:

dither daemon reload

Without the reload, the daemon keeps watching the previous library until it next restarts.

Examples

Fresh user, default everything (interactive prompt):

$ dither init

Welcome to dither.

? Where should your library live? › ~/.dither/library

✓ wrote ~/.dither/config.json
✓ created library at ~/.dither/library
✓ pre-downloaded model weights

next: dither plugin install <path>

Adopt an existing folder as the library:

$ dither init --library ~/Documents/dither
✓ wrote ~/.dither/config.json
✓ using library at ~/Documents/dither
✓ pre-downloaded model weights

next: dither plugin install <path>

CI / offline:

$ dither init --library ~/.dither/library --no-download
✓ wrote ~/.dither/config.json
✓ created library at ~/.dither/library
• weights skipped (--no-download)

next: dither plugin install <path>

Re-run is a no-op:

$ dither init
dither is already initialized at ~/.dither
  library: ~/.dither/library