Skip to content

CLI Reference

tryke

A Rust-based Python test runner with a Jest-style API.

Tryke discovers tests by walking the project's import graph, runs them across a pool of pre-warmed worker processes, and streams results through a pluggable reporter. It can also run as a long-lived server that keeps workers warm between file changes for sub-second feedback in editors.

Running tryke with no subcommand starts watch mode. Run tryke <command> --help to see detailed help for a subcommand.

Usage:

tryke [OPTIONS] [COMMAND]

Commands:

Options:

  • --cache-dir <CACHE_DIR>

Directory for tryke's persistent discovery cache.

Overrides [tool.tryke] cache_dir in pyproject.toml. Defaults to <project-root>/.tryke/cache.

  • --no-progress

Disable the terminal's native graphical progress bar.

By default tryke emits OSC 9;4 progress sequences, which terminals like Ghostty, WezTerm, iTerm2, Windows Terminal, and ConEmu render as a native progress indicator (taskbar badge, tab badge, etc.). Pass this flag in CI or in terminals that mis-render the sequence.

  • -q, --quiet

Decrease logging verbosity

  • -v, --verbose

Increase logging verbosity

tryke clean

Remove tryke's persistent discovery cache.

Deletes the default <project-root>/.tryke/cache directory. When --cache-dir or [tool.tryke] cache_dir points at a custom directory, only tryke-owned cache files inside that directory are removed.

Usage:

tryke clean [OPTIONS]

Options:

  • --cache-dir <CACHE_DIR>

Directory for tryke's persistent discovery cache.

Overrides [tool.tryke] cache_dir in pyproject.toml. Defaults to <project-root>/.tryke/cache.

  • --no-progress

Disable the terminal's native graphical progress bar.

By default tryke emits OSC 9;4 progress sequences, which terminals like Ghostty, WezTerm, iTerm2, Windows Terminal, and ConEmu render as a native progress indicator (taskbar badge, tab badge, etc.). Pass this flag in CI or in terminals that mis-render the sequence.

  • -q, --quiet

Decrease logging verbosity

  • --root <ROOT>

Project root used to resolve the default cache directory

  • -v, --verbose

Increase logging verbosity

tryke graph

Print the import dependency graph for the project.

Renders the static import graph that drives discovery, change detection, and watch mode. Defaults to printing reachable modules from the project root; pass --changed to see only the slice affected by recent edits, or --fixtures to inspect the fixture dependency graph (@fixture + Depends()) instead.

Usage:

tryke graph [OPTIONS]

Options:

  • --base-branch <BASE_BRANCH>

Base branch for --changed. Uses git merge-base diff

  • --cache-dir <CACHE_DIR>

Directory for tryke's persistent discovery cache.

Overrides [tool.tryke] cache_dir in pyproject.toml. Defaults to <project-root>/.tryke/cache.

  • --changed

Show only the slice affected by changes since HEAD.

Requires git. Combine with --base-branch to diff against a branch instead of the working tree.

  • --connected-only

Hide isolated nodes (files with no dependents and no dependencies)

  • -e, --exclude <EXCLUDE>

Exclude files or directories from discovery

  • --fixtures

Print the fixture dependency graph instead of the import graph.

Renders the graph of @fixture-decorated functions and the Depends() edges between them, useful for debugging fixture resolution.

  • -i, --include <INCLUDE>

Include files or directories even if excluded by pyproject.toml

  • --no-progress

Disable the terminal's native graphical progress bar.

By default tryke emits OSC 9;4 progress sequences, which terminals like Ghostty, WezTerm, iTerm2, Windows Terminal, and ConEmu render as a native progress indicator (taskbar badge, tab badge, etc.). Pass this flag in CI or in terminals that mis-render the sequence.

  • -q, --quiet

Decrease logging verbosity

  • --root <ROOT>

Project root used for discovery

  • -v, --verbose

Increase logging verbosity

tryke server

Start a persistent worker server.

Spawns and pre-warms the worker pool, runs initial discovery, and listens on 127.0.0.1:<port> for JSON-RPC 2.0 requests. Clients connect with tryke test --port to run tests without paying the cold-start cost. The server also watches the filesystem and broadcasts discover_complete notifications when the test list changes.

Usage:

tryke server [OPTIONS]

Options:

  • --cache-dir <CACHE_DIR>

Directory for tryke's persistent discovery cache.

Overrides [tool.tryke] cache_dir in pyproject.toml. Defaults to <project-root>/.tryke/cache.

  • -e, --exclude <EXCLUDE>

Exclude files or directories from discovery

  • -i, --include <INCLUDE>

Include files or directories even if excluded by pyproject.toml

  • --no-progress

Disable the terminal's native graphical progress bar.

By default tryke emits OSC 9;4 progress sequences, which terminals like Ghostty, WezTerm, iTerm2, Windows Terminal, and ConEmu render as a native progress indicator (taskbar badge, tab badge, etc.). Pass this flag in CI or in terminals that mis-render the sequence.

  • --port <PORT>

Port for the server to listen on

Default: 2337

  • --python <PYTHON>

Path to the Python interpreter used to spawn worker processes.

Overrides [tool.tryke] python in pyproject.toml. Defaults to python on Windows / python3 on Unix from PATH. Relative values in pyproject.toml resolve against the directory containing pyproject.toml; bare names go through PATH. See the Configuration guide for the full rules.

  • -q, --quiet

Decrease logging verbosity

  • --root <ROOT>

Project root used for discovery and execution

  • -v, --verbose

Increase logging verbosity

tryke test

Collect and run tests.

Discovers tests by walking the project's static import graph from the project root, then runs them across a worker pool. Filter with positional path arguments, -k (name expression), or -m (tag expression). Combine with --changed to run only tests affected by uncommitted changes, or --watch for an interactive rerun loop.

Examples:

tryke test
tryke test tests/test_math.py
tryke test tests/test_math.py:42
tryke test -k "parse and not slow"
tryke test --changed --base-branch origin/main
tryke test --watch

Usage:

tryke test [OPTIONS] [PATHS]...

Arguments:

  • [PATHS]...

File paths or file:line specs to restrict collection.

Each path may be a file, a directory, or file.py:LINE to target the test defined at that line. Directory paths recurse into all .py files under them.

Options:

  • -a, --all

In watch mode, rerun the full test set on every change.

Disables affected-test computation; every save triggers a full run. Useful when the import graph is stale or for very small suites.

  • --base-branch <BASE_BRANCH>

Base branch for --changed / --changed-first diff.

Compares against git merge-base <base> HEAD instead of the working tree. Typical CI usage: --changed --base-branch origin/main.

  • --cache-dir <CACHE_DIR>

Directory for tryke's persistent discovery cache.

Overrides [tool.tryke] cache_dir in pyproject.toml. Defaults to <project-root>/.tryke/cache.

  • --changed

Run only tests affected by uncommitted changes.

Uses git diff to find changed .py files, then walks the import graph forward to find every test that transitively depends on a changed module. Combine with --base-branch to diff against a branch instead of the working tree.

  • --changed-first

Run changed tests first, then the remaining tests.

Same affected-set computation as --changed, but unaffected tests are appended to the run rather than skipped. Gives fast feedback on the diff while still verifying the full suite.

  • --collect-only

Collect tests without running them.

Prints the discovered test list and exits. Useful for verifying that filters select the tests you expect.

  • --dist <DIST>

How tests are distributed across workers

Possible values: test, file, group

Default: test

  • -e, --exclude <EXCLUDE>

Exclude files or directories from discovery.

Overrides the [tool.tryke] exclude list in pyproject.toml. May be repeated.

  • -x, --fail-fast

Stop after the first failing test

  • -k, --filter <FILTER>

Filter tests by name expression.

Supports substring matching with boolean operators (and, or, not) and parentheses, matched against the full test name including any describe() group prefix.

Examples: -k "math", -k "math and not slow", -k "(parse or lex) and not regression".

  • -i, --include <INCLUDE>

Include files or directories even if excluded by pyproject.toml.

Useful for opting a single subtree back into discovery without rewriting the project-wide exclude list. May be repeated.

  • -m, --markers <MARKERS>

Filter tests by tag expression.

Matches against the tags=[...] argument on the @test decorator. Same boolean syntax as -k.

Examples: -m "slow", -m "fast and not network".

  • --maxfail <MAXFAIL>

Stop after N failures.

Mutually informative with --fail-fast (which is --maxfail 1).

  • --no-progress

Disable the terminal's native graphical progress bar.

By default tryke emits OSC 9;4 progress sequences, which terminals like Ghostty, WezTerm, iTerm2, Windows Terminal, and ConEmu render as a native progress indicator (taskbar badge, tab badge, etc.). Pass this flag in CI or in terminals that mis-render the sequence.

  • --now

In watch mode, run tests immediately on watch startup.

By default watch mode starts idle and waits for the first file change before running anything. Pass --now to kick off a full run on startup, the same way each subsequent change does.

Requires --watch.

  • --port <PORT>

Run against an already-running tryke server instead of spawning fresh workers.

Pass --port alone to use the default 2337, or --port 9000 to target a specific port. The server keeps workers pre-warmed and the import graph cached, so this is significantly faster for repeated runs.

  • --python <PYTHON>

Path to the Python interpreter used to spawn worker processes.

Overrides [tool.tryke] python in pyproject.toml. Defaults to python on Windows / python3 on Unix from PATH. The interpreter is the user's responsibility — tryke does not validate it. Activate the appropriate venv (or use uv run tryke ...) and the default will pick it up.

Relative python values in pyproject.toml (e.g., .venv/bin/python3) resolve against the directory containing pyproject.toml, not the cwd. Bare names (python3, pypy) are looked up via PATH. See the Configuration guide for the full resolution rules.

Not compatible with --port; configure the interpreter on the server instead.

  • -q, --quiet

Decrease logging verbosity

  • --reporter <REPORTER>

Reporter format for test output

Possible values: text, json, dot, junit, llm, next, sugar

Default: text

  • --root <ROOT>

Project root used for discovery and execution.

Defaults to the current working directory. Discovery, the import graph, and pyproject.toml resolution are all anchored here.

  • -v, --verbose

Increase logging verbosity

  • -w, --watch

Watch the project and rerun affected tests on each change.

Enters an interactive loop: tryke watches all .py files (respecting .gitignore), and on each save it walks the import graph from the modified file forward to find affected tests, restarts the worker pool, and reruns just those tests. Press q to quit, enter to run all tests, or c to clear results.

  • -j, --workers <WORKERS>

Number of worker processes.

Defaults to min(test_count, cpu_count). Set to 1 to run tests in a single worker (useful when debugging concurrency issues).