CLI reference
Global flag: -C, --cwd <dir> — run as if started in <dir> (must appear before the command). Every command supports --json; output carries schemaVersion: 1.
Exit codes: 0 = OK · 1 = a verification check failed · 2 = usage or runtime error.
thoth init
Detects the project and writes .thoth/config.json (minimal: { "version": 1 }). Also creates .thoth/.gitignore so reports and runtime data stay out of Git — your own .gitignore is never modified.
--force — overwrite an existing config with defaults.
thoth scan
Shows what Thoth knows about the repository: package manager, languages, frameworks, discovered verification commands (and checks it looked for but couldn't find), file counts, and dependency-graph statistics.
thoth status
Quick overview: repository, environment, pending change count, a quick blast estimate, the latest report's verdict, and risk.
thoth impact
Blast radius of the current change. Output distinguishes upper bound (conservative) — every file that transitively depends on a changed file — from symbol-linked — files containing a symbol that actually references the changed code. Also shows direct and indirect dependents, changed symbols and exports, relevant tests, files with no test linkage, risk factors with reasons, and explicit unknowns.
| Flag | Meaning |
|---|---|
| --staged | Only staged changes (index vs base) |
| --base <rev> | Compare against a revision other than HEAD |
| --explain | Evidence trail for each conclusion + per-stage timings |
thoth tests
Lists test files relevant to the current change, with reason and confidence, plus changed files with no discoverable test link.
thoth verify
Runs trusted verification for the change and writes a report to .thoth/reports/.
| Flag | Meaning |
|---|---|
| (default) | relevant mode: typecheck, lint, relevant tests |
| --full | Full test suite plus build |
| --checks <ids> | Run only these checks; e2e never runs unless listed |
| --dry-run | Print the plan, run nothing |
| --no-save | Don't persist the report |
| --staged / --base | Same semantics as impact |
Only commands discovered from package.json scripts or .thoth/config.json run — executed without a shell, with a timeout, and the working tree is diffed before and after to detect commands that mutate files.
thoth report [id]
Prints the latest saved report, a specific id, or --list all ids.
thoth mcp
Starts the MCP server over stdio (what agents connect to).
thoth mcp setup [--agent cursor|claude|codex] [--write] thoth mcp status
thoth doctor
Environment self-check: Node version, Git binary, repository state, package.json, discovered checks, .thoth/ writability, and confirms no network is required. Exits 2 if a required check fails.
.thoth/config.json
Minimal by design — everything is optional:
{
"version": 1,
"ignore": ["generated"],
"include": ["dist"],
"checks": {
"test": ["pnpm", "vitest", "run"],
"e2e": null
},
"risk": { "sensitivePatterns": ["billing"], "dataPatterns": ["schema"] },
"verification": { "timeoutMs": 600000, "outputTailLines": 40 },
"reports": { "retain": 50 },
"impact": { "maxDepth": 8 }
}Unknown keys and invalid values are rejected with a readable warning and defaults are used. A config declaring a version newer than the running Thoth is refused with an upgrade hint.