fallow: codebase intelligence for TypeScript and JavaScript

These flags are inherited by fallow commands (dead-code, check, dupes, health, flags, security, fix, watch, list, init, migrate). Some commands reject flags that are not meaningful for that surface.

Reference

Flag	Description
`-r, --root <PATH>`	Project root directory (default: current working directory)
`-c, --config <PATH>`	Path to config file (default: auto-detected)
`-f, --format <FORMAT>`	Output format: `human` (default), `json`, `sarif`, `compact`, `markdown`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`, `badge`. Alias: `--output`. `--format json` is compact by default; add `--pretty` for indented output.
`--pretty`	Indent `--format json` output for manual inspection. JSON is compact by default so machine and agent consumers get the same schema with less output; this flag restores human-readable indentation. Applies only to JSON output. SARIF, Code Climate, baselines, snapshots, caches, and other persisted JSON keep their existing presentation regardless of this flag.
`-q, --quiet`	Suppress progress bars and status messages
`--no-cache`	Disable incremental caching (force full re-parse)
`--threads <N>`	Number of parser threads (default: available parallelism)
`--max-file-size <MB>`	Skip source files larger than this many megabytes at discovery instead of parsing them (default `5`; `0` disables the guard). Guards against the out-of-memory blowup a single multi-megabyte generated, vendored, or bundled file causes on large repositories, and also skips large one-line minified JS assets while the guard is enabled. Declaration files (`.d.ts`) are always analyzed regardless of size. Skipped files are reported on stderr and in `--format json` under `workspace_diagnostics` (`kind: "skipped-large-file"` or `"skipped-minified-file"`). Also settable via `FALLOW_MAX_FILE_SIZE`.
`--changed-since <REF>` (alias: `--base`)	Only report issues in files changed since this git ref
`--diff-file <PATH>`	Path to a unified diff (e.g. `git diff --unified=0 main...HEAD`) used to narrow source-anchored findings to lines inside an added hunk. Point findings (unused-export, unresolved-import, boundary-violation, etc.) drop when their source line is not in the diff; range findings (complexity hotspots, clone families) drop when their `[start_line, end_line]` does not overlap the diff. Project-level findings (unused deps, catalog entries, dependency overrides) bypass the analysis filter because they anchor at fixed `package.json` / `pnpm-workspace.yaml` lines a PR rarely touches even when it semantically caused them. Sticky PR/MR summaries can set `FALLOW_SUMMARY_SCOPE=diff` to filter those project-level findings too. Also drives line-level scoping of the runtime-coverage `hot-path-touched` verdict. Pass `-` as the path or use `--diff-stdin` to read the diff from stdin (`gh pr diff \| fallow audit --diff-file -`). When combined with `--changed-since`, the diff filter wins for line-level filtering and `--changed-since` still scopes file discovery; a one-line stderr note records the precedence. Falls back to the `FALLOW_DIFF_FILE` env var when omitted.
`--diff-stdin`	Read the unified diff from stdin instead of a file. Equivalent to `--diff-file -`. Mutually exclusive with a non-stdin `--diff-file PATH` value. Useful for piping `gh pr diff` or `git diff` directly into fallow.
`--churn-file <PATH>`	Import change history from a `fallow-churn/v1` JSON file instead of `git log`, so `fallow health --hotspots` / `--ownership` / `--targets` work on projects with no git repository (Yandex Arc, Mercurial, Perforce). Resolved relative to `--root`; wins over git when both are present. The file is authoritative for the analysis window, so `--since` then only labels output. A malformed file fails with exit 2. Affects the churn-backed health signals only; `audit`, `impact`, and `--changed-since` still require git. See `fallow health` › Importing churn from a non-git VCS.
`--baseline <PATH>`	Compare against a previously saved baseline file
`--save-baseline <PATH>`	Save the current results as a baseline file
`--fail-on-regression`	Fail if issue count increased beyond tolerance vs a regression baseline
`--tolerance <N>`	Allowed increase: `"2%"` (percentage) or `"5"` (absolute). Default: `"0"`
`--regression-baseline <PATH>`	Path to regression baseline file (default: `.fallow/regression-baseline.json`)
`--save-regression-baseline <PATH>`	Save current issue counts as a regression baseline
`--production`	Production mode: exclude test/story/dev files, only start/build scripts
`--no-production`	Force production mode off for every analysis, overriding a project config’s `production: true`. Conflicts with `--production`.
`--production-dead-code`	Per-analysis production mode for dead-code in bare combined runs and `fallow audit`. See Per-analysis production mode.
`--production-health`	Per-analysis production mode for health in bare combined runs and `fallow audit`.
`--production-dupes`	Per-analysis production mode for duplication in bare combined runs and `fallow audit`.
`-w, --workspace <PATTERNS>`	Scope output to one or more workspaces. Accepts exact names, globs matched against both the package name AND the workspace path (`apps/`, `@scope/`), and `!`-prefixed negations (`!apps/legacy`). Values can be comma-separated (`-w web,admin`) or the flag can be repeated. Quote patterns containing `!` or glob chars to avoid shell expansion.
`--changed-workspaces <REF>`	Git-derived monorepo CI scoping: scope output to workspaces containing any file changed since `REF` (e.g. `origin/main`, `HEAD~1`). Auto-derives the workspace set from `git diff` so CI jobs don’t hand-maintain a `--workspace` list. Mutually exclusive with `--workspace`. A missing ref or non-git directory is a hard error (exit 2), not a silent full-scope fallback. Root-only diffs map to 0 workspaces and exit 0 with no issues.
`--performance`	Show pipeline timing breakdown
`--explain`	In human format, prints a `Description:` line under each section header. In JSON format, includes metric definitions in the output `_meta` object. Always enabled for MCP.
`--ci`	CI mode: equivalent to `--format sarif --fail-on-issues --quiet`
`--fail-on-issues`	Exit with code 1 if issues are found
`--sarif-file <PATH>`	Write SARIF output to a file (in addition to the primary `--format` output)
`-o, --output-file <PATH>`	Write the report to a file instead of stdout, for any `--format` (no ANSI codes). Useful on large projects where the terminal scrollback truncates the top. Progress and a `Report written to <path>` confirmation stay on stderr (suppressed by `--quiet`). Valid with `dead-code`, `dupes`, `health`, `security`, and bare invocation; composes with `--sarif-file`.
`--report-path-prefix <PREFIX>`	Prefix prepended to every path in the CI-facing formats (`github-annotations`, `github-summary`, `codeclimate`, `review-github`, `review-gitlab`). CI platforms address files by repository-root-relative path, so when the analyzed project lives in a subdirectory (e.g. `packages/app/`), paths need that offset. fallow detects the offset via the git toplevel automatically; this flag overrides the detection. Pass an empty string to disable rebasing and emit paths relative to `--root`.
`--group-by <MODE>`	Group output by CODEOWNERS ownership (`owner`), first directory component (`directory`), workspace package (`package`), or GitLab CODEOWNERS section (`section`). When active, all output formats partition issues into labeled groups.
`--summary`	Print a one-line summary of issue counts at the end of the run. In JSON format, adds a `summary` counts object to the output.
`--only <check,dupes,health>`	Run only specific analyses when no subcommand is given
`--skip <check,dupes,health>`	Skip specific analyses when no subcommand is given
`--coverage <PATH>`	Feed Istanbul coverage data to the embedded health analysis in combined mode. Falls back to `FALLOW_COVERAGE`, then `health.coverage`, then auto-detection.
`--coverage-root <PATH>`	Absolute prefix to strip from Istanbul coverage paths in combined mode. Falls back to `FALLOW_COVERAGE_ROOT`, then `health.coverageRoot`.
`--dupes-mode <MODE>`	Override duplicate detection mode in combined mode. Falls back to the config value when unset. Mirrors the standalone `fallow dupes --mode`.
`--dupes-threshold <PCT>`	Override the duplication percentage failure threshold in combined mode. Falls back to the config value when unset. Mirrors the standalone `fallow dupes --threshold`.
`--dupes-min-tokens <N>`	Override the minimum token count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `fallow dupes --min-tokens`.
`--dupes-min-lines <N>`	Override the minimum line count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `fallow dupes --min-lines`.
`--dupes-min-occurrences <N>`	Override the minimum clone occurrences in combined mode (must be `>= 2`). Falls back to the config value when unset. Mirrors the standalone `fallow dupes --min-occurrences`.
`--dupes-skip-local`	Only report cross-directory duplicates in combined mode. Falls back to the config value when unset. Mirrors the standalone `fallow dupes --skip-local`.
`--dupes-cross-language`	Enable TypeScript to JavaScript duplicate matching in combined mode. Falls back to the config value when unset. Mirrors the standalone `fallow dupes --cross-language`.
`--dupes-ignore-imports`	Exclude module wiring from duplicate detection in combined mode (default). Falls back to the config value when unset. Mirrors the standalone `fallow dupes --ignore-imports`.
`--dupes-no-ignore-imports`	Count module wiring as clone candidates in combined mode (opt out of the default exclusion). Conflicts with `--dupes-ignore-imports`. Mirrors the standalone `fallow dupes --no-ignore-imports`.
`--score`	Compute health score (0-100 with letter grade) in combined mode. Enables the health delta header in PR comments. Also available on `fallow health`.
`--trend`	Compare current health metrics against the most recent saved snapshot. Implies `--score`. Also available on `fallow health`.
`--save-snapshot [PATH]`	Save a vital signs snapshot for trend tracking. Default path: `.fallow/snapshots/<timestamp>.json`. Forces file-scores and hotspot computation. Also available on `fallow health`.
`--include-entry-exports`	Report unused exports in entry files instead of auto-marking them as used. Catches typos in framework exports (e.g. `meatdata` instead of `metadata`). Also configurable via `includeEntryExports: true` in your fallow config; the CLI flag wins when set.

Repository-root paths in CI formats

CI platforms resolve file paths against the repository root: GitHub annotations, CodeClimate reports in GitLab, and inline review comments all reject or misplace paths relative to anything else. When --root points at a subdirectory of a git repository (a monorepo package like packages/app/), the CI-facing formats (github-annotations, github-summary, codeclimate, review-github, review-gitlab) therefore emit repository-root-relative paths: fallow detects the offset between --root and the git toplevel and prepends it automatically. --report-path-prefix overrides the detected offset for containerized or vendored checkouts where the git toplevel does not match the CI workspace; an empty string (--report-path-prefix '') disables rebasing entirely and restores --root-relative paths. Supplied diffs (--diff-file, --diff-stdin, FALLOW_DIFF_FILE) get the same treatment in reverse: fallow detects whether the diff’s paths are repository-root-relative or --root-relative and filters findings accordingly. A diff that parses but touches no analyzable files (deletion-only, binary-only, or empty) filters the report to zero findings; only a diff whose paths cannot be placed at all falls back to the full-scope report, with a warning saying so.

Loaded config disclosure

When fallow loads a config file (either auto-discovered or via --config), it prints a single line to stderr:

loaded config: /repo/.fallowrc.json

This makes it obvious which .fallowrc.json is in effect, especially in monorepos where multiple configs may exist. The line is suppressed when:

--quiet is set
--format is anything other than human (json, sarif, compact, markdown, codeclimate, gitlab-codequality, pr-comment-github, pr-comment-gitlab, review-github, review-gitlab, badge)

For deeper inspection (the resolved config with extends merged), use the dedicated fallow config subcommand.

Examples

# Analyze a project in a different directory
fallow dead-code -r /path/to/project

# Use a specific config file
fallow dead-code -c configs/fallow-strict.json

# JSON output with no progress messages
fallow dead-code -f json --quiet

# Limit parallelism to 4 threads
fallow dead-code --threads 4

# Scope to a single workspace package
fallow dead-code -w @myorg/ui

# Scope to whichever workspaces changed since origin/main (CI primitive)
fallow --changed-workspaces origin/main

# Show timing breakdown
fallow dead-code --performance

# Group issues by CODEOWNERS ownership
fallow dead-code --group-by owner

# Group issues by top-level directory
fallow dead-code --group-by directory

# Group issues by workspace package
fallow dead-code --group-by package

# Group issues by GitLab CODEOWNERS section
fallow dead-code --group-by section

# Health score in combined mode
fallow --score

# Save a snapshot and track trends
fallow --save-snapshot
fallow --trend

Per-analysis production mode

Bare combined runs (fallow with no subcommand) and fallow audit accept three per-analysis production flags so you can enable production mode for one analysis without forcing it on the others:

# Treat health as production-only, leave dead-code and dupes in full-tree mode
fallow --production-health

# Audit changed files with production-only health
fallow audit --base main --production-health

The matching environment variables FALLOW_PRODUCTION_DEAD_CODE, FALLOW_PRODUCTION_HEALTH, and FALLOW_PRODUCTION_DUPES accept the same set of values as FALLOW_PRODUCTION (true, false, 1, 0, yes, no, on, off). The production config field also accepts a per-analysis object:

{
  "production": {
    "deadCode": false,
    "health": true,
    "dupes": false
  }
}

Precedence (highest to lowest): CLI flags (--production, --production-{dead-code,health,dupes}), per-analysis env var (FALLOW_PRODUCTION_HEALTH, etc.), global env var (FALLOW_PRODUCTION), config (production: { ... } or production: true). The legacy boolean form (--production, production: true, FALLOW_PRODUCTION=true) is unchanged and still applies to every analysis. The per-analysis CLI flags are rejected when used with a subcommand other than audit (e.g. fallow dead-code --production-health errors). Use the bare command or the per-analysis env vars in that case.

Grouped output

The --group-by flag partitions all issues into labeled groups. This works with every output format and every subcommand.

Mode	Grouping	Requires
`owner`	CODEOWNERS file ownership. Auto-probes `CODEOWNERS`, `.github/CODEOWNERS`, `.gitlab/CODEOWNERS`, `docs/CODEOWNERS`. First owner on multi-owner lines wins.	A CODEOWNERS file (or set `codeowners` in config)
`directory`	First path component (e.g. `src/utils/foo.ts` groups under `src`)	Nothing
`package`	Workspace package name (e.g. `@myorg/ui`). Issues are grouped by the package they belong to.	A monorepo with workspace packages
`section`	GitLab CODEOWNERS `[Section]` header name. Distinct sections stay in distinct groups even when they share a default reviewer, so teams with one shared lead reviewer across many sections get per-section triage instead of one giant bucket.	A GitLab-style CODEOWNERS file with at least one `[Section]` header

With --format json, the output shape changes to a grouped envelope:

{
  "kind": "dead-code-grouped",
  "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": [] }
  ]
}

For --group-by section, each group also carries an owners array with the section’s default owners:

{
  "kind": "dead-code-grouped",
  "grouped_by": "section",
  "total_issues": 6,
  "groups": [
    {
      "key": "billing",
      "owners": ["@core-reviewers", "@alice", "@bob"],
      "total_issues": 2,
      "unused_exports": []
    },
    {
      "key": "notifications",
      "owners": ["@core-reviewers", "@alice", "@bob"],
      "total_issues": 1,
      "unused_exports": []
    }
  ]
}

Section and owner groups are not interchangeable: owner collapses all sections that share a lead reviewer into a single bucket, while section preserves the [Section] headers as stable group keys across reviewer rotation.

Set a custom CODEOWNERS path via the codeowners field in .fallowrc.json if your file isn’t in a standard location.

Incremental caching

Fallow caches parsed file data between runs to skip unchanged files. On the second run, only modified files are re-parsed. The rest are loaded from cache. How it works:

Each file is hashed with xxh3 (extremely fast, non-cryptographic)
If the hash matches the cached version, parsing is skipped entirely
The module graph is rebuilt from cached + freshly-parsed data

Use --performance to see cache hit rates and per-stage timings. This is helpful for diagnosing slow runs.

fallow dead-code --performance

 Discovery     12ms   (142 files)
 Parsing       48ms   (23 parsed, 119 cached)
 Resolution    15ms
 Analysis       8ms
 Total         83ms

Use --no-cache to force a full re-parse. This is useful after major refactors or when debugging unexpected results.

fallow dead-code --no-cache

Set cache.dir in the project config or FALLOW_CACHE_DIR in the environment to move the persistent cache out of .fallow/cache.bin. The env var wins when both are present.

FALLOW_CACHE_DIR=/tmp/fallow-cache fallow dead-code

--no-cache makes every run a cold start. Use it only for debugging unexpected results.

Environment variables

Set defaults for format and quiet mode via environment variables.

Configuration

Full config file reference for project-level settings.

Commands

Global flags

Reference

Repository-root paths in CI formats

Loaded config disclosure

Examples

Per-analysis production mode

Grouped output

Incremental caching

See also

Environment variables

Configuration

​Reference

​Repository-root paths in CI formats

​Loaded config disclosure

​Examples

​Per-analysis production mode

​Grouped output

​Incremental caching

​See also

Environment variables

Configuration

Reference

Repository-root paths in CI formats

Loaded config disclosure

Examples

Per-analysis production mode

Grouped output

Incremental caching

See also