---
title: CLI Reference — irradiate
description: Complete command-line reference for irradiate. All commands, flags, and options for run, results, show, and cache.
---

<!-- Auto-generated by scripts/gen-cli-docs.sh from clap definitions in src/main.rs -->
<!-- Do not edit manually — run: bash scripts/gen-cli-docs.sh -->

# CLI Reference

## Global

```
irradiate [OPTIONS] <COMMAND>
```

| Flag        | Description   |
| ----------- | ------------- |
| `--version` | Print version (irradiate 0.4.1) |
| `--help`    | Print help    |

## `irradiate run`

Run mutation testing

```bash
irradiate run [OPTIONS] [PATHS]...
```

### Options

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--mutant <MUTANT>` | -- | Filter to specific mutant names (advanced — test only these mutants) |
| `--paths-to-mutate <PATHS_TO_MUTATE>` | -- | Alias for positional paths, for backward compatibility. Prefer positional: `irradiate run src/` instead of `--paths-to-mutate src/` |
| `--tests-dir <TESTS_DIR>` | -- | Path to test directory (default: "tests", overrides pyproject.toml) |
| `--workers <WORKERS>` | -- | Number of worker processes |
| `--timeout-multiplier <TIMEOUT_MULTIPLIER>` | `10` | Timeout multiplier (applied to baseline test duration) |
| `--no-stats` | -- | Skip stats collection, test all mutants against all tests |
| `--covered-only` | -- | Skip mutants with no test coverage |
| `--python <PYTHON>` | -- | Python interpreter path (auto-detected from venv if not set) |
| `--max-worker-memory <MAX_WORKER_MEMORY>` | `0` | Recycle workers whose RSS exceeds this threshold in megabytes (0 to disable) |
| `--isolate` | -- | Run each mutant in a fresh subprocess (slower, better isolation) |
| `--verify-survivors` | -- | After the main run, re-test survived mutants in isolate mode to detect false negatives from warm-session state leakage. No-op when --isolate is set |
| `--fail-under <FAIL_UNDER>` | -- | Fail with exit code 1 if mutation score (killed/tested*100) is below this threshold. Value must be between 0.0 and 100.0. Only applied when at least one mutant is tested |
| `--diff <DIFF>` | -- | Only mutate functions changed since this git ref (e.g., main, HEAD~3). Requires a git repository |
| `--report <REPORT>` | -- | Generate a report in the specified format (json = Stryker schema v2) |
| `-o, --output <OUTPUT>` | -- | Output path for the generated report (default: irradiate-report.<format>) |
| `--sample <SAMPLE>` | -- | Randomly sample a subset of mutants. Values 0.0-1.0 are fractions (e.g. 0.1 = 10%). Values > 1 are absolute counts (e.g. 100 = test exactly 100 mutants) |
| `--sample-seed <SAMPLE_SEED>` | `0` | RNG seed for --sample (default: 0 for reproducibility) |
| `--no-cache` | -- | Ignore cached results — re-test all mutants from scratch |
| `--stats-timeout <STATS_TIMEOUT>` | `300` | Timeout in seconds for stats collection (default: 300). Increase for large test suites (e.g., 600 for 10K+ tests) |
| `--pytest-args <PYTEST_ARGS>` | -- | Extra arguments to pass to every pytest invocation (appended after config file values). Example: --pytest-args=-v --pytest-args=--tb=short |
| `--worker-timeout <WORKER_TIMEOUT>` | `30` | Timeout in seconds for workers to complete test collection (default: 30). Increase for projects with slow imports (e.g. --worker-timeout 120 for tinygrad/torch) |
| `--cache-pre-sync <CACHE_PRE_SYNC>` | -- | Shell command to run before the mutation testing run (e.g. download remote cache). Overrides cache_pre_sync in pyproject.toml |
| `--cache-post-sync <CACHE_POST_SYNC>` | -- | Shell command to run after the mutation testing run (e.g. upload cache to remote). Overrides cache_post_sync in pyproject.toml |
| `--type-checker <TYPE_CHECKER>` | -- | Run a type checker to filter mutants caught by static analysis. Accepts a preset name (mypy, pyright, ty) or a raw command string. Mutants that introduce type errors are marked as killed (exit code 37) |
| `--no-source-patch` | -- | Disable source-patch mutations for decorated functions. Only trampoline-compatible functions (@property, @classmethod, @staticmethod) will be mutated. Skips the slower source-patch phase |
| `--ignore <IGNORE>` | -- | Glob patterns for files to exclude from mutation. Can be repeated. Merged with do_not_mutate from pyproject.toml |
| `-h, --help` | -- | Print help |

### Examples

```bash
irradiate run                                    # basic run (auto-detects src/)
irradiate run src/mylib                          # mutate a specific path
irradiate run --diff main                        # incremental: changed functions only
irradiate run --fail-under 80                    # CI gate
irradiate run --report html -o report.html       # HTML report
irradiate run --isolate                          # full subprocess isolation
irradiate run --verify-survivors                 # re-check survivors after warm run
irradiate run --python .venv/bin/python          # specific interpreter
irradiate run --mutant mylib.x_add__irradiate_3  # test one specific mutant
irradiate run --workers 4 --covered-only         # tuning
irradiate run --sample 0.1                       # test 10% of mutants (fast CI)
irradiate run --sample 50 --sample-seed 42       # test exactly 50, reproducible
irradiate run --no-cache                         # ignore cache, re-test everything
irradiate run --ignore "src/vendor/*"            # exclude files from mutation
irradiate run --type-checker mypy                # filter mutants caught by type checker
irradiate run --pytest-args "--ignore=tests/e2e" # skip a test directory
```

## `irradiate results`

Display mutation testing results

```bash
irradiate results [OPTIONS]
```

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--all` | -- | Show all mutants, not just survived |
| `--json` | -- | Output machine-readable JSON instead of text |
| `--report <REPORT>` | -- | Generate a report in the specified format (json = Stryker schema v2) |
| `-o, --output <OUTPUT>` | -- | Output path for the generated report (default: irradiate-report.<format>) |
| `-h, --help` | -- | Print help |

## `irradiate show`

Show diff for a specific mutant

```bash
irradiate show <MUTANT_NAME>
```

| Argument        | Description                      |
| --------------- | -------------------------------- |
| `<MUTANT_NAME>` | e.g. `mylib.x_func__irradiate_1` |

## `irradiate cache clean`

Remove the local result cache.

```bash
irradiate cache clean
```

## `irradiate cache gc`

Garbage-collect old or excess cache entries

```bash
irradiate cache gc [OPTIONS]
```

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--max-age <MAX_AGE>` | -- | Maximum age for cache entries (e.g. "30d", "24h", "1h30m"). Default: "30d". Overrides cache_max_age in pyproject.toml |
| `--max-size <MAX_SIZE>` | -- | Maximum total cache size (e.g. "1gb", "500mb"). Default: "1gb". Overrides cache_max_size in pyproject.toml |
| `--dry-run` | -- | Show what would be pruned without deleting anything |
| `-h, --help` | -- | Print help |

Defaults can be set in pyproject.toml via `cache_max_age` and `cache_max_size`. See [Remote Cache](../guide/remote-cache.md).

## Configuration

`run` options can also be set in `pyproject.toml` under `[tool.irradiate]`. CLI flags override config. See [Configuration](../getting-started/configuration.md).

## Mutant name format

| Python source              | Mutant name                    |
| -------------------------- | ------------------------------ |
| `def add()` in `mylib`     | `mylib.x_add__irradiate_1`     |
| `class Foo` method `bar()` | `mylib.xǁFooǁbar__irradiate_1` |

The `x_` prefix avoids collisions. The `ǁ` (U+01C1) separator encodes class membership.
