CLI Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Mutineer Command Line Interface (CLI) provides the primary entry point for performing mutation testing on Ruby projects. It allows you to initialize project configurations, execute mutation runs against test suites, and generate machine-readable reports for CI/CD integration. The CLI focuses on providing a zero-dependency experience by leveraging the Ruby standard library and Prism.
Sources: skills/mutineer/SKILL.md:1-5, lib/mutineer/init.rb:1-10
Command: init
The mutineer init command creates a starter .mutineer.yml configuration file in your current directory. It detects project structures to suggest an initial run command.
Usage and Options
mutineer init [--rails] [--force] [--help]
| Option | Description |
|---|---|
--rails | Configures the template for a Rails project, setting rails: true and suggesting Rails-specific source folders like app/models. |
--force | Overwrites an existing .mutineer.yml file. |
--help | Displays the usage message. |
Sources: lib/mutineer/init.rb:14-36
Initialization Logic
When you run init, the module performs the following steps:
- Validates that no source paths are provided as arguments.
- Checks if
.mutineer.ymlalready exists; if it does, it requires--forceto proceed. - Generates a YAML template containing default operators.
- Searches for standard Ruby/Rails directories (
lib,app/models,app/services) to recommend a firstruncommand.
Sources: lib/mutineer/init.rb:41-65
The diagram above shows the decision flow when initializing a Mutineer configuration.
Sources: lib/mutineer/init.rb:39-70
Command: run
The mutineer run command executes the mutation testing process. It mutates the specified source code, runs the associated tests, and calculates a mutation score.
Primary Execution Arguments
| Argument / Flag | Type | Description |
|---|---|---|
<source...> | Path | One or more Ruby source files or directories to mutate. |
--test <test> | Path | One or more test files to run against the mutants. |
--threshold <float> | Float | The minimum mutation score (0-100) required to exit with success. |
--format <type> | String | The output format: human (default), json, or html. |
--output <file> | Path | Redirects the report output to a specific file. |
--since <ref> | String | Only mutates lines changed since the specified Git reference. |
--baseline <file> | Path | Compares results against a stored JSON report to detect regressions. |
Sources: skills/mutineer/SKILL.md:18-22, lib/mutineer/reporter.rb:34-45
Execution Workflow
Mutineer processes mutants through a lifecycle of discovery, execution, and reporting.
The flow describes how the run command moves from identifying code to final threshold gating.
Sources: lib/mutineer/reporter.rb:34-60, skills/mutineer/SKILL.md:28-35
Exit Codes
Mutineer uses specific exit codes to signal the result of a run, which is critical for CI/CD pipeline automation.
| Code | Meaning |
|---|---|
0 | Success: The mutation score meets or exceeds the threshold, and no baseline regressions were detected. |
1 | Failure: The score is below the threshold, a baseline regression occurred, a runtime error was encountered, or the run was too "broken" to be trusted (e.g., too many timeouts/errors). |
2 | Usage Error: An invalid flag was used, a path was unreadable, or the baseline file was missing. |
Sources: rake/docs_contract.rb:64-67, lib/mutineer/reporter.rb:108-124, skills/mutineer/SKILL.md:65-72
Reporting and Output
The Reporter class handles the transformation of mutation results into various formats.
Report Formats
- Human: A text-based summary printed to the terminal, including diffs for surviving mutants.
- JSON: A versioned machine-readable report (Schema Version 1.8). It includes detailed metadata, mutation IDs, and source breakdowns.
- HTML: A self-contained file with styling for viewing results in a browser.
Sources: lib/mutineer/reporter.rb:27-45, lib/mutineer/reporter.rb:208-215
Completeness Gate
The CLI implements a "broken share" limit. If more than 10% of attempted mutants result in a no_verdict status (due to errors or timeouts), the CLI fails the threshold gate even if the calculated score is high. This prevents a broken test harness from reporting a misleadingly high mutation score.
Sources: lib/mutineer/reporter.rb:14-24, lib/mutineer/reporter.rb:440-444
This diagram illustrates how the Reporter determines output based on CLI flags.
Sources: lib/mutineer/reporter.rb:34-65
Summary
The Mutineer CLI acts as a gatekeeper for code quality by enforcing mutation score thresholds. It provides flexible initialization via init and detailed execution control via run. By using standardized exit codes and multi-format reporting, it integrates into both local development loops and automated CI environments.