The CLI performs a small, ordered workflow:
- Refresh the cached shared dictionary only when the configured authority is newer than the valid local cache.
- Load the cached dictionary and merge
typos.local.tomlwhen the overlay is present. - Render
typos.tomldeterministically. - Atomically write the rendered content, or compare it with the tracked file
when
--checkis set.
The refresh operation preserves a valid cache when the configured authority is
temporarily unavailable. With the default source, a run that has no valid cache
and cannot reach the authority falls back to the bundled snapshot, so shared
policy can always be established; an explicit --source has no such fallback
and fails instead.
The gate command performs the same workflow in write mode and then runs the
pinned Typos binary and the phrase check, so a consumer needs no separate Typos
invocation. Entries under [phrases.corrections] are never rendered, because
Typos tokenizes hyphenated phrases as separate words and would silently ignore
them; the gate applies them itself.