Commands
The first three are one pipeline — impact-based pytest selection — and run
computes the whole of it in-process. The other two stand alone.
| Command | What it does |
|---|---|
changed-symbols | Map the working tree’s diff to the Python symbols it changed |
impacted-tests | Walk from those changed symbols to the tests that reach them |
run | Run pytest on exactly those tests |
audit | Report unreferenced and test-only symbols in the files you name |
doctor | Show the resolved workspace and tyf binary, then exit |
guide | Print agent-facing instructions: setup, triage or tune |
Global flags
| Flag | Default | Meaning |
|---|---|---|
--workspace PATH | auto-detect | Project root to resolve symbols against |
--format human|json | human | Output shape |
-v, --verbose | off | Debug logging to stderr (RUST_LOG wins if set) |
Exit codes
| Code | Meaning |
|---|---|
0 | The run completed and nothing was flagged |
1 | The run completed and findings were reported |
2 | The run could not complete — tyf missing, bad workspace, malformed output |
That table is audit’s. The split between 1 and 2 is what
makes it usable in CI: a failing check and a broken setup are different
problems.
changed-symbols and impacted-tests never return 1: their output is an
inventory, not a verdict on one. When impacted-tests cannot trust its own
answer it says so in the report (verdict: run_all) and still exits 0 —
“run everything” is a usable answer for a pre-commit hook, and failing the hook
because the analysis was inconclusive only teaches people to bypass it.
run is the exception to the table. Its own failures exit 2 as
usual, but once pytest starts the exit code is pytest’s, verbatim — that is
the hook contract. A selection that turns out to impact no tests exits 0
without spawning anything.
Prerequisites per command
changed-symbols needs only git — it parses Python with tree-sitter, so it
works in a checkout that has never had ty installed. impacted-tests needs
both git and tyf, but looks for tyf only once it knows the walk will
actually run. run needs those two plus pytest, which it resolves from
GERENUK_PYTEST, then pytest-command in pyproject.toml, then PATH.
audit and doctor need tyf on PATH. guide needs nothing at all, not
even a repository.