> ## Documentation Index > Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt > Use this file to discover all available pages before exploring further. # fallow dead-code > CLI reference for fallow dead-code. Scan entry points, trace reachable exports, and report unused files, exports, dependencies, and types. Analyze your project for dead code. Fallow scans entry points, traces all reachable exports, and reports anything that isn't used. Running bare `fallow` now runs **all analyses** (dead code, duplication, and health). Use `fallow dead-code` to run dead code analysis only. `fallow check` remains as a hidden alias for `fallow dead-code`. ```bash theme={null} fallow dead-code fallow check # Hidden alias for fallow dead-code ``` ## Options ### Output | Flag | Description | | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-f, --format ` | Output format: `human` (default), `json`, `sarif`, `compact`, `markdown`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab` | | `-q, --quiet` | Suppress progress output | | `--fail-on-issues` | Exit with code 1 if issues are found | | `--sarif-file ` | Write SARIF output to a file (in addition to `--format`) | | `--ci` | CI mode: sets format to SARIF, enables fail-on-issues, suppresses progress. Individual flags can still override. | | `--explain` | Add metric explanations. In human format, explanations are always shown. In JSON format, adds a `_meta` object with metric descriptions and docs links. | | `--group-by ` | Group output by `owner` (CODEOWNERS), `directory` (first path component), `package` (workspace package), or `section` (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata). See [global flags](/cli/global-flags#reference). | | `--summary` | Print a one-line summary of issue counts at the end of the run. In JSON format, adds a `summary` counts object. | ### Filtering | Flag | Description | | :------------------------------------- | :------------------------------------------------------------------------------- | | `--unused-files` | Only report unused files | | `--unused-exports` | Only report unused exports | | `--unused-types` | Only report unused types | | `--private-type-leaks` | Opt in to private type leak API hygiene findings and only report that issue type | | `--unused-deps` | Only report unused dependencies | | `--unused-optional-deps` | Only report unused optional dependencies | | `--unused-enum-members` | Only report unused enum members | | `--unused-class-members` | Only report unused class members | | `--unresolved-imports` | Only report unresolved imports | | `--unlisted-deps` | Only report unlisted dependencies | | `--duplicate-exports` | Only report duplicate exports | | `--circular-deps` | Only report circular dependencies | | `--boundary-violations` | Only report boundary violations | | `--stale-suppressions` | Only report stale suppression comments and `@expected-unused` JSDoc tags | | `--type-only-deps` | Only report type-only dependencies | | `--unused-catalog-entries` | Only report unused pnpm catalog entries | | `--empty-catalog-groups` | Only report empty named pnpm catalog groups | | `--unresolved-catalog-references` | Only report package references to missing pnpm catalog entries | | `--unused-dependency-overrides` | Only report unused pnpm dependency overrides | | `--misconfigured-dependency-overrides` | Only report malformed pnpm dependency overrides | | `--include-dupes` | Also run duplication analysis and cross-reference with dead code | ### Scoping | Flag | Description | | :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--file ` | Scope output to specific files. Accepts multiple values. Only issues in the specified files are reported. Project-wide dependency issues are suppressed. Warns on non-existent paths. Useful for lint-staged integration. | | `--include-entry-exports` | Also report unused exports in entry files (package.json `main`/`exports`, framework pages, etc.). By default, exports in entry files are assumed to be consumed externally. This flag catches typos like `meatdata` instead of `metadata` in framework-convention exports. The flag is global, so it works on combined mode (`fallow --include-entry-exports`) and `fallow audit`. Configurable persistently via `includeEntryExports: true` in your fallow config; the CLI flag wins when set. | ### Incremental | Flag | Description | | :----------------------- | :----------------------------------------------------------- | | `--changed-since ` | Only check files changed since a git ref | | `--baseline ` | Compare against a previously saved baseline file | | `--save-baseline ` | Save current results as a baseline file | | `--production` | Production mode (exclude test/story/dev files) | | `--top ` | Show only the top N items per issue category in human output | ### Regression detection | Flag | Description | | :---------------------------------- | :----------------------------------------------------------------------------- | | `--fail-on-regression` | Fail if issue count increased beyond tolerance vs a regression baseline | | `--tolerance ` | Allowed increase: `"2%"` (percentage) or `"5"` (absolute). Default: `"0"` | | `--regression-baseline ` | Path to regression baseline file (default: `.fallow/regression-baseline.json`) | | `--save-regression-baseline ` | Save current issue counts as a regression baseline | These flags help you understand how fallow resolves your code and where time is spent. | Flag | Description | | :----------------------------- | :------------------------------- | | `--trace ` | Trace usage of a specific export | | `--trace-file ` | Show all edges for a file | | `--trace-dependency ` | Show where a dependency is used | | `--performance` | Show pipeline timing breakdown | ```bash theme={null} # Why is formatDate reported as unused? fallow dead-code --trace src/utils.ts:formatDate # What imports/exports does this file have? fallow dead-code --trace-file src/utils.ts # Where is lodash used? fallow dead-code --trace-dependency lodash # Pipeline performance breakdown fallow dead-code --performance ``` ## Examples ```bash Basic analysis theme={null} fallow dead-code ``` ```bash CI integration theme={null} # JSON output for CI pipelines fallow dead-code --format json # SARIF for GitHub Code Scanning fallow dead-code --format sarif > results.sarif # Markdown for PR comments fallow dead-code --format markdown | gh pr comment --body-file - # Fail on any issues fallow dead-code --fail-on-issues ``` ```bash Incremental workflows theme={null} # Only check changed files in a PR fallow dead-code --changed-since main # Save a baseline, then check against it fallow dead-code --save-baseline fallow-baselines/dead-code.json fallow dead-code --baseline fallow-baselines/dead-code.json ``` ```bash Regression detection theme={null} # Save a regression baseline (e.g., on the main branch) fallow dead-code --save-regression-baseline # Fail if issue count regressed (zero tolerance) fallow dead-code --fail-on-regression # Allow up to 2% increase fallow dead-code --fail-on-regression --tolerance 2% # Allow up to 5 absolute new issues fallow dead-code --fail-on-regression --tolerance 5 # Custom baseline path fallow dead-code --fail-on-regression --regression-baseline .fallow/my-baseline.json ``` ```bash Production mode theme={null} # Exclude test and dev files fallow dead-code --production ``` ```bash File scoping theme={null} # Only report issues in specific files fallow dead-code --file src/utils.ts # Multiple files (e.g., from lint-staged) fallow dead-code --file src/utils.ts --file src/helpers.ts # Catch typos in entry file exports (e.g., meatdata vs metadata) fallow dead-code --include-entry-exports ``` ## Regression detection Save a regression baseline on your main branch, then compare on subsequent runs (e.g., in PR checks) to prevent issue count from growing. **Workflow:** 1. Save a regression baseline on `main`: ```bash theme={null} fallow dead-code --save-regression-baseline ``` This writes issue counts to `.fallow/regression-baseline.json` (or a custom path). 2. On each PR, compare against the baseline: ```bash theme={null} fallow dead-code --fail-on-regression ``` Exits with code 1 if the total issue count exceeds the baseline plus the configured tolerance. 3. Optionally set a tolerance to allow small fluctuations: ```bash theme={null} fallow dead-code --fail-on-regression --tolerance 2% # percentage fallow dead-code --fail-on-regression --tolerance 5 # absolute ``` When `--fail-on-regression` is used with `--format json`, the output includes an optional `regression` object: ```json theme={null} { "regression": { "status": "pass", "baseline_total": 42, "current_total": 45, "delta": 3, "tolerance": 2.0, "tolerance_kind": "percentage", "exceeded": false } } ``` | Field | Description | | :--------------- | :---------------------------------------------------------------------- | | `status` | `pass`, `exceeded`, or `skipped` | | `baseline_total` | Issue count from the baseline file | | `current_total` | Issue count from the current run | | `delta` | `current_total - baseline_total` | | `tolerance` | Configured tolerance value | | `tolerance_kind` | `percentage` or `absolute` | | `exceeded` | Whether the delta exceeds the tolerance | | `reason` | Only present when `status` is `skipped` (e.g., baseline file not found) | These flags also work with `fallow dupes` and bare `fallow` (all analyses). The regression check compares total issue counts across all enabled analyses. ## Example output ```bash title="$ fallow dead-code --format compact" theme={null} unused-file:src/server/jobs/worker.ts unused-file:src/features/savings/hooks/usePotGroups.ts unused-file:src/server/jobs/cron.ts unused-export:src/server/jobs/queue.ts:61:enqueueJobDelayed unused-export:src/server/jobs/queue.ts:206:sweepStuckProcessingJobs unused-export:src/components/Card/index.ts:1:CardFooter ``` ## Grouped output Use `--group-by` to partition issues by ownership or directory. This works with all output formats. ```bash theme={null} # Group by CODEOWNERS (auto-probes CODEOWNERS, .github/CODEOWNERS, .gitlab/CODEOWNERS, docs/CODEOWNERS) fallow dead-code --group-by owner # Group by first directory component fallow dead-code --group-by directory # Group by workspace package fallow dead-code --group-by package # Group by GitLab CODEOWNERS section (requires a file with [Section] headers) fallow dead-code --group-by section ``` With `--format json`, grouped output wraps the normal structure: ```json theme={null} { "grouped_by": "owner", "total_issues": 12, "groups": [ { "key": "@frontend-team", "total_issues": 8, "unused_files": [...], "unused_exports": [...] }, { "key": "@backend-team", "total_issues": 4, "unused_exports": [...] } ] } ``` Set a custom CODEOWNERS path via the `codeowners` field in `.fallowrc.json` if your file isn't in a standard location. ## Fix suggestions in JSON output When using `--format json`, every issue includes an `actions` array with machine-actionable fix and suppress hints. This lets agents and CI scripts programmatically decide how to resolve each finding. ```json theme={null} { "path": "src/utils.ts", "export_name": "helperFn", "line": 10, "actions": [ { "type": "remove-export", "auto_fixable": true, "description": "Remove the unused export from the public API" }, { "type": "suppress-line", "auto_fixable": false, "description": "Suppress with an inline comment above the line", "comment": "// fallow-ignore-next-line unused-export" } ] } ``` Each action has: | Field | Description | | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | One of 14 fix action types in kebab-case (e.g. `remove-export`, `remove-file`, `suppress-line`, `add-to-config`) | | `auto_fixable` | `true` when `fallow fix` can handle this action automatically | | `description` | Human-readable explanation of the action | | `comment` | *(optional)* The inline suppression comment to add | | `note` | *(optional)* Additional context for non-auto-fixable items | | `config_key` | *(optional)* The config key to modify, e.g. `"ignoreDependencies"` for dependency issues | | `value` | *(optional)* Value to write at `config_key`. Scalar for keys like `ignoreDependencies`; array of `{ file, exports }` rule objects for `ignoreExports` | | `value_schema` | *(optional)* URL pointing at the JSON Schema fragment that describes `value`. Agents that want to validate the payload before writing it into a user's config can fetch the linked schema and apply it | | `scope` | *(optional)* Present on `duplicate_exports` suppress actions as `"per-location"` since those span multiple files | Re-export findings include a warning note about public API surface impact. Dependency issues use `add-to-config` suppress (not inline comments) with the concrete package name and `config_key: "ignoreDependencies"`. ## Additional JSON fields When using `--format json`, the output may include these additional top-level objects: ### `entry_points` Lists all resolved entry point files that root the module graph: ```json theme={null} { "entry_points": [ "src/index.ts", "src/cli.ts", "src/workers/sync.ts" ] } ``` ### `summary` When `--summary` is used, a `summary` counts object is included: ```json theme={null} { "summary": { "unused_files": 3, "unused_exports": 12, "unused_types": 2, "private_type_leaks": 0, "unused_dependencies": 1, "unresolved_imports": 0, "circular_dependencies": 1, "total_issues": 19 } } ``` `private_type_leaks` is present in JSON output for schema stability, but the rule is off by default. It is populated only when enabled with `--private-type-leaks` or with `private-type-leaks` set to `warn` or `error` in configuration. ### `used_in_workspaces` Unused dependency findings can include `used_in_workspaces` when a package is unused in the declaring workspace but imported elsewhere in the monorepo: ```json theme={null} { "unused_dependencies": [ { "package_name": "lodash-es", "location": "dependencies", "path": "packages/shared/package.json", "line": 5, "used_in_workspaces": ["packages/consumer"] } ] } ``` In human, markdown, GitHub, and GitLab output this appears as "imported in" or an "Imported elsewhere" column. Treat these as workspace placement issues: move the dependency to the consuming workspace instead of auto-removing it. ### `baseline_deltas` When `--baseline` is used, a `baseline_deltas` object shows changes since the baseline: ```json theme={null} { "baseline_deltas": { "added": 3, "removed": 5, "unchanged": 14 } } ``` ## Stale suppression detection Fallow detects `// fallow-ignore` comments and `/** @expected-unused */` JSDoc tags that no longer match any issue. This prevents suppression comments from accumulating after the underlying issues are resolved. ```bash theme={null} # Only report stale suppressions fallow dead-code --stale-suppressions # JSON output includes stale_suppressions array fallow dead-code --format json --stale-suppressions ``` Two types of staleness are detected: | Origin | When it's stale | | :----------------------------------------------------- | :---------------------------------------------------------------------------- | | `// fallow-ignore-next-line` / `// fallow-ignore-file` | The suppression no longer matches any issue on the target line or in the file | | `/** @expected-unused */` JSDoc tag | The tagged export is now imported by another module | The `stale-suppressions` rule defaults to `warn`. Promote to `error` for CI enforcement: ```jsonc theme={null} { "rules": { "stale-suppressions": "error" } } ``` When using `--format json`, stale suppressions appear in the `stale_suppressions` array: ```json theme={null} { "stale_suppressions": [ { "path": "src/utils.ts", "line": 5, "col": 0, "origin": { "type": "inline_comment", "issue_type": "unused-export", "is_file_level": false } }, { "path": "src/lib.ts", "line": 10, "col": 0, "origin": { "type": "jsdoc_tag", "export_name": "createWidget" } } ] } ``` Use `/** @expected-unused */` instead of `// fallow-ignore-next-line` when you want fallow to alert you if a suppressed export later becomes used. Both are tracked for staleness, but `@expected-unused` communicates intent more clearly. ## See also How fallow detects dead code. Configure severity and thresholds per rule. Analyze only shipping code.