CLI Reference
All Prune commands, flags, and exit codes.
Prune is invoked as:
prune <command> [flags]If no command is given, Prune prints usage to stderr and exits.
Commands
version
Prints the installed version of Prune and exits.
prune versionOutput:
prune version 0.3.0-beta.1No flags are accepted by this command.
init
Generates a prune.yaml configuration file with default values in the current directory.
prune initFlags:
| Flag | Type | Default | Description |
|---|---|---|---|
--out | string | prune.yaml | Output path for the generated configuration file |
Example — write config to a custom path:
prune init --out config/prune.yamlOutput on success:
✅ Created prune.yamlThis command does not overwrite an existing file — it will fail if the destination path already exists.
scan
Analyzes the project and reports dead code findings.
prune scan [flags]Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--config | string | prune.yaml | Path to the Prune configuration file |
--format | string | pretty | Output format: pretty, json, ndjson, or table (alias for pretty) |
--min-confidence | string | safe | Minimum confidence level to include in output: safe, likely_dead, or review |
--paths | string (repeatable) | (from config) | Override scan paths. Can be specified multiple times |
--fail-on-findings | bool | false | Exit with a non-zero status code if any findings match the confidence filter |
--stream | bool | false | Enable streaming mode — emit findings incrementally as files are processed |
--stream-interval | int | 250 | Interval in milliseconds between streaming flushes |
--compact | bool | false | Show only summary counts, without individual findings |
--only | string | "" | Show only findings with this confidence level: safe, review, or likely_dead |
--deletable | bool | false | Show only files that are safe to delete (no living imports) |
Examples:
# Basic scan using default config
prune scan
# Scan using a specific config file
prune scan --config path/to/prune.yaml
# Output as JSON
prune scan --format json
# Fail the process if any findings are found (for CI/CD)
prune scan --fail-on-findings
# Override scan paths
prune scan --paths src/components --paths src/lib
# Show only summary counts
prune scan --compact
# Show only findings with likely_dead confidence
prune scan --only likely_dead
# Show only files safe to delete
prune scan --deletable
# Stream findings as NDJSON in real time
prune scan --stream --format ndjson
# Stream with a faster flush interval
prune scan --stream --stream-interval 100Notes on streaming:
When --stream is enabled and --format is json, the format is automatically promoted to ndjson. The pretty and table formats are not supported in streaming mode — only ndjson produces streamed output; for other formats, the stream flag enables batched collection but output is still printed once after completion.
rules
Lists all available rule IDs and their descriptions.
prune rulesNo flags are accepted.
Output:
RULE ID DESCRIPTION
unused_function Function declared but never used
unused_variable Variable declared but never used
unused_export Exported symbol never imported
unused_file File never imported or referenced
possible_dynamic_usage Possible dynamic usage detected via pattern match
suspicious_dynamic_usage Dynamic usage that blocks certaintyhelp
Prints the top-level usage message to stdout.
prune help
# or
prune -h
# or
prune --helpExit Codes
| Code | Condition |
|---|---|
0 | Command completed successfully. In scan, this means no error occurred — findings may still be present. |
1 | An error occurred (unrecognized command, config load failure, I/O error, etc.) |
1 | --fail-on-findings is set and at least one finding passes the --min-confidence filter |
The scan command exits 0 even if there are findings, unless --fail-on-findings is explicitly set. This makes it safe to use in report-only mode without affecting pipeline status.