Fallow reads a small set of environment variables to override default behavior. These are useful for CI pipelines, editor integrations, and the MCP server.
| Variable | Description | Values |
|---|---|---|
FALLOW_FORMAT | Default output format | human, json, sarif, compact, markdown (md), codeclimate, gitlab-codequality (gitlab-code-quality), pr-comment-github, pr-comment-gitlab, review-github, review-gitlab, badge, github-annotations, github-summary |
FALLOW_QUIET | Suppress progress output | 1 or true |
FALLOW_BIN | Path to the fallow binary | Any valid path |
FALLOW_EXTENDS_TIMEOUT_SECS | Timeout for fetching URL extends | Seconds (default: 5) |
FALLOW_PRODUCTION | Global production-mode override for every analysis | true/false/1/0/yes/no/on/off |
FALLOW_PRODUCTION_DEAD_CODE | Per-analysis production override for dead-code (combined runs and fallow audit) | Same values as FALLOW_PRODUCTION |
FALLOW_PRODUCTION_HEALTH | Per-analysis production override for health | Same values as FALLOW_PRODUCTION |
FALLOW_PRODUCTION_DUPES | Per-analysis production override for duplication | Same values as FALLOW_PRODUCTION |
FALLOW_REVIEW_GUIDANCE | Add collapsed "What to do" blocks to review-github / review-gitlab inline comments | 1, true, yes, on |
FALLOW_SUMMARY_SCOPE | Sticky PR/MR summary scope for pr-comment-github / pr-comment-gitlab. all keeps project-level dependency/catalog/override findings outside the diff; diff applies the diff filter to those findings too. Inline review comments are unaffected | all (default), diff |
FALLOW_PR_COMMENT_LAYOUT | Sticky PR/MR summary layout for pr-comment-github / pr-comment-gitlab. Use gate-only when a native Check Run or Code Quality widget is the primary surface | default, compact, gate-only, details |
FALLOW_CACHE_DIR | Override the extraction cache directory | Any valid path |
FALLOW_AUDIT_BASE | Pin the fallow audit comparison base when --base / --changed-since is unset (escape hatch for the agent gate and forks) | Any git ref (e.g. origin/main, upstream/main) |
FALLOW_AUDIT_CACHE_MAX_AGE_DAYS | Max age of persistent reusable fallow audit base-snapshot worktree caches | Whole days (default 30; 0 disables) |
FALLOW_IMPACT_STORE_MAX_AGE_DAYS | Reclaim per-project fallow impact stores older than this; a recorded run sweeps stale stores (e.g. from deleted repos) | Whole days (unset / 0 keeps every store forever) |
FALLOW_MAX_FILE_SIZE | Skip source files larger than this many megabytes at discovery and skip large one-line minified JS assets while the guard is enabled (mirrors --max-file-size; .d.ts always analyzed) | Whole megabytes (default 5; 0 disables) |
FALLOW_UPDATE_CHECK | Disable the local human-TTY upgrade nudge and background latest-version check | off, 0, false, disabled, no |
FALLOW_SUGGESTIONS | Suppress the next_steps[] array of read-only follow-up commands in JSON output and the human Next: line | off, 0, false, no, disabled (default on) |
FALLOW_TELEMETRY | Opt-in telemetry mode, off by default (see what it collects) | off/on/inspect (plus 0/1/true/false/disabled/enabled/debug/log) |
FALLOW_TELEMETRY_DISABLED | Admin/fleet telemetry kill switch (top precedence) | 1, true, yes, on |
FALLOW_TELEMETRY_DEBUG | Forces inspect mode (outranks FALLOW_TELEMETRY) | 1, true, yes, on |
DO_NOT_TRACK | Honored as a top-precedence telemetry kill switch | 1, true, yes, on |
FALLOW_AGENT_SOURCE | Declare the calling agent for telemetry classification (never enables telemetry) | codex, claude_code, cursor, copilot, opencode, aider, roo, windsurf, gemini (aliases gemini_cli/antigravity), cline, continue, zed, goose, other_known, unknown, none |
FALLOW_INTEGRATION_SURFACE | Declare the telemetry integration surface (set by the MCP server on the CLI it invokes; never enables telemetry) | mcp, lsp, vscode, napi, programmatic |
FALLOW_MCP_TOOL | Declare the MCP tool name for the telemetry mcp_tool dimension (set by the MCP server; validated against a fixed allowlist, otherwise dropped; never enables telemetry) | An allowlisted MCP tool name (for example find_dupes, audit) |
Set the default output format so you don't need to pass --format every time.
export FALLOW_FORMAT=json
fallow dead-code # Outputs JSON without --format flagThe --format CLI flag takes precedence over FALLOW_FORMAT when both are set.
Suppress progress bars and status messages. Useful in CI environments or when piping output.
export FALLOW_QUIET=1
fallow dead-code # No progress output, only resultsEquivalent to passing --quiet on every command.
Path to the fallow binary. Used by the MCP server (fallow-mcp) to locate the fallow CLI.
export FALLOW_BIN=/usr/local/bin/fallow
fallow-mcp # MCP server uses the specified binaryDefaults to fallow on PATH when not set.
Timeout in seconds for fetching remote configs via https:// URLs in the extends field.
export FALLOW_EXTENDS_TIMEOUT_SECS=10
fallow dead-code # URL extends have 10s to respondDefaults to 5 seconds when not set.
Directory for the persistent extraction cache. Wins over the cache.dir config field when both are set.
export FALLOW_CACHE_DIR=/tmp/fallow-cache
fallow dead-code # cache files are stored under /tmp/fallow-cacheBy default, fallow stores the cache in .fallow/cache.bin under the project root. Use this env var when the project checkout is read-only, when CI has a dedicated cache volume, or when multiple workspace copies should share a stable cache location.
--no-cache disables the cache entirely; this env var is then irrelevant.
Maximum on-disk extraction cache (.fallow/cache.bin) size in megabytes. Wins over the cache.maxSizeMb config field when both are set.
export FALLOW_CACHE_MAX_SIZE=64
fallow dead-code # cache capped at 64 MBDefaults to 256 (MB) when not set. The cache triggers LRU eviction when its serialized size crosses 80% of the cap and evicts down to 60%. Intended for CI runners with disk quotas; local dev machines on full-size disks rarely need to touch this knob.
--no-cache disables the cache entirely; this env var is then irrelevant.
Pins the fallow audit comparison base. It takes effect only when neither --base nor --changed-since is passed, so the precedence is --base flag, then FALLOW_AUDIT_BASE, then auto-detection.
export FALLOW_AUDIT_BASE=upstream/main
fallow audit # compares against upstream/main instead of the auto-detected baseWhen unset, fallow audit auto-detects the base as the git merge-base (fork point) against the branch's upstream or the remote default (origin/HEAD, then origin/main, then origin/master). That is the right answer for most repositories, but two cases want an explicit pin:
origin is your fork (which can lag the real upstream), so set FALLOW_AUDIT_BASE=upstream/main to compare against the true upstream.fallow hooks install --target agent generates a hook that runs bare fallow audit. If your team works entirely in git worktrees and never updates the local default branch, the env var lets you pin the base without editing the generated script (which is regenerated on reinstall).A malformed value (a ref with disallowed characters) fails the audit with exit code 2 rather than being silently ignored, so a typo surfaces immediately.
Maximum age (in whole days, since last reuse or fresh create) of a persistent reusable fallow audit base-snapshot worktree cache. Older entries are removed at the top of the next fallow audit invocation. Wins over the audit.cacheMaxAgeDays config field when both are set; during fallow audit-cache prune, the --max-age-days flag wins over this variable.
export FALLOW_AUDIT_CACHE_MAX_AGE_DAYS=7
fallow audit --base origin/main # caches older than 7 days are reclaimedDefaults to 30 days when not set. Setting the value to 0 disables the GC entirely (escape hatch for CI runners that prune /tmp out-of-band). Invalid values (non-integer, negative) silently fall back to the config field / default; a typo in a runner env var does not fail audits.
The sweep runs once per fallow audit invocation, walks fallow-owned base-snapshot cache entries only (never unrelated temp-directory content), and never removes a cache entry that another in-flight fallow audit is using (per-entry kernel flock(2) guard). On reclaim, fallow writes a single fallow: reclaimed N stale base-snapshot caches line to stderr (unless --quiet is set) so the disk-space recovery is observable. To apply the same GC policy on demand and see every per-entry decision, use fallow audit-cache prune.
Reclaim per-project fallow impact stores that have not been touched in this many whole days. Impact keeps one small history file per project in your user config directory; over time, projects you delete from disk leave their stores behind. Set this so a recorded run prunes them.
export FALLOW_IMPACT_STORE_MAX_AGE_DAYS=90
fallow audit --base origin/main # impact stores untouched for 90+ days are reclaimedUnset (the default) keeps every store forever; 0 and invalid values are treated the same way (no sweep), so a typo never deletes history. Age is the store file's modification time, and any recorded run rewrites the file, so an actively-tracked project never ages out. The sweep never touches the project you just recorded, never deletes the advisory .lock sidecars, and never the global impact.json opt-in toggle. Because impact only records on developer machines (never in CI), this is purely local housekeeping.
Local human runs can show a one-line upgrade hint when a cached latest-version check says the installed fallow is stale. The hint is suppressed for machine formats, CI, quiet runs, and non-TTY agent paths. Set FALLOW_UPDATE_CHECK=off to disable both the hint and the background latest-version check on that machine. DO_NOT_TRACK and FALLOW_TELEMETRY_DISABLED also suppress it.
dead-code, health, dupes, bare fallow, and audit add a top-level next_steps[] array of read-only follow-up commands to their --format json output (and a one-line Next: hint to bare fallow's human output on a TTY), computed from the run's findings. Set FALLOW_SUGGESTIONS=off (or 0/false/no/disabled) to suppress it; this is the escape hatch for CI consumers that snapshot-diff raw JSON output. The variable is inherited by the MCP-spawned CLI, so it also disables next_steps on MCP responses.
FALLOW_PRODUCTION mirrors the --production CLI flag and turns production mode on for every analysis. The per-analysis vars (FALLOW_PRODUCTION_DEAD_CODE, FALLOW_PRODUCTION_HEALTH, FALLOW_PRODUCTION_DUPES) target a single analysis when running bare combined mode (fallow with no subcommand) or fallow audit.
# Run combined mode with production-only health, full-tree dead-code and dupes
export FALLOW_PRODUCTION_HEALTH=true
fallow --format json --quietPrecedence (highest to lowest):
--production, --production-{dead-code,health,dupes})FALLOW_PRODUCTION_HEALTH, etc.)FALLOW_PRODUCTION)production: true legacy form, or production: { health: true, ... } per-analysis form)Per-analysis env beats global env, so FALLOW_PRODUCTION=false FALLOW_PRODUCTION_HEALTH=true runs health in production mode and the other analyses in non-production mode. Single-subcommand runs (e.g. fallow health) still respect FALLOW_PRODUCTION_HEALTH even though the per-analysis CLI flag is rejected with a subcommand: pass --production or set the per-analysis env var.
Set FALLOW_FORMAT=json and FALLOW_QUIET=1 in CI pipelines for clean machine-readable output.
Path to Istanbul coverage data (coverage-final.json) used for accurate per-function CRAP scores in fallow health, fallow audit, and bare fallow. An explicit CLI flag or MCP tool parameter wins when set. CLI and typed MCP routes then read this variable before falling back to health.coverage from config.
export FALLOW_COVERAGE=./coverage/coverage-final.json
fallow healthAbsolute prefix to strip from Istanbul coverage paths before matching files. Use it when coverage was generated in a different checkout root, such as CI or Docker. An explicit CLI flag or MCP tool parameter wins when set. CLI and typed MCP routes then read this variable before falling back to health.coverageRoot from config.
Per-file size ceiling in megabytes for source discovery (default 5; 0 = no limit). Source files strictly larger are skipped before parsing, guarding against out-of-memory blowups from a single multi-megabyte generated or bundled file. The --max-file-size CLI flag wins when both are set. Declaration files (.d.ts) are always analyzed.
These variables tune the review-github / review-gitlab / pr-comment-github / pr-comment-gitlab output formats. The bundled GitHub Action and GitLab CI template set them for you; set them yourself only when rendering these formats outside the bundled integrations.
| Variable | Effect |
|---|---|
FALLOW_ROOT | Project root the review renderers read source from for suggestion blocks. Set alongside --root. |
FALLOW_REVIEW_GUIDANCE | Set to true to append collapsed per-finding guidance blocks to review inline comment bodies. |
FALLOW_SUMMARY_SCOPE | all (default) keeps project-level dependency/catalog/override findings outside the diff filter in PR-comment summaries; diff applies the diff filter to them too. |
FALLOW_PR_COMMENT_LAYOUT | Sticky PR/MR summary layout for pr-comment-github / pr-comment-gitlab. Values: default, compact, gate-only, or details. Use gate-only when a native Check Run or Code Quality widget is the primary surface. |
FALLOW_DIFF_CONTEXT | Line radius around changed diff lines when scoping findings to a diff (default 3). |
FALLOW_BOT_LOGIN | Bot or token username treated as fallow's own when reconciling existing PR/MR comments. Required when posting with a personal access token. |
FALLOW_API_RETRIES | Maximum HTTP attempts for review-comment reconciliation API calls (default 3). |
FALLOW_API_RETRY_DELAY | Floor delay in seconds between HTTP retries (default 2); a server-supplied Retry-After overrides it on 429 responses. |
These variables configure the paid runtime intelligence layer and fallow cloud connectivity. See fallow license and fallow coverage.
| Variable | Effect |
|---|---|
FALLOW_LICENSE | License JWT (full string); intended for shared CI runners. |
FALLOW_LICENSE_PATH | File path containing the license JWT. |
FALLOW_LICENSE_SKEW_TOLERANCE_SECONDS | Clock-skew tolerance applied to the license JWT's iat claim (default 86400). |
FALLOW_COV_BIN | Explicit path override for the fallow-cov runtime-coverage sidecar binary. |
FALLOW_COV_BINARY_PATH | Secondary sidecar path override, checked after FALLOW_COV_BIN (air-gapped installs, distro-packaged sidecars). |
FALLOW_RUNTIME_COVERAGE_SOURCE | Set to cloud to select cloud runtime coverage in fallow coverage analyze without passing --cloud. |
FALLOW_REPO | owner/repo fallback for fallow coverage analyze --cloud when --repo is not passed. |
FALLOW_API_URL | Base URL override for fallow cloud API calls (staging / local-dev). |
FALLOW_API_KEY | fallow cloud bearer token for coverage upload commands. |
FALLOW_CA_BUNDLE | Path to a PEM certificate bundle for fallow cloud and provider HTTP calls (replaces the default WebPKI roots; include public roots plus any private CA). |
Set these in the MCP server's env block; the spawned CLI inherits them. Full reference: MCP integration.
| Variable | Effect |
|---|---|
FALLOW_TIMEOUT_SECS | Per-tool-call CLI subprocess timeout in seconds (default 120). |
FALLOW_DIFF_FILE | Path to a unified diff that scopes all findings by changed line. |
FALLOW_CHANGED_SINCE | Git ref that scopes file discovery for analysis tools. |
FALLOW_INTEGRATION_SURFACE | Telemetry surface override for non-CLI surfaces; set by the MCP server on the CLI it spawns. |
FALLOW_MCP_TOOL | Telemetry per-tool dimension; set by the MCP server alongside FALLOW_INTEGRATION_SURFACE=mcp. |
The complete machine-readable list ships in the environment_variables block of fallow schema.