> ## 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.
# Environment variables
> Override fallow defaults with environment variables like FALLOW_FORMAT and FALLOW_QUIET. Useful for CI pipelines, editor integrations, and MCP.
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`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`, `badge` |
| `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_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`](/cli/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](/cli/telemetry) mode, off by default (see [what it collects](/explanations/telemetry)) | `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](/cli/telemetry#agent-source) 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](/explanations/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](/explanations/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`) |
## FALLOW\_FORMAT
Set the default output format so you don't need to pass `--format` every time.
```bash theme={null}
export FALLOW_FORMAT=json
fallow dead-code # Outputs JSON without --format flag
```
The `--format` CLI flag takes precedence over `FALLOW_FORMAT` when both are set.
## FALLOW\_QUIET
Suppress progress bars and status messages. Useful in CI environments or when piping output.
```bash theme={null}
export FALLOW_QUIET=1
fallow dead-code # No progress output, only results
```
Equivalent to passing `--quiet` on every command.
## FALLOW\_BIN
Path to the fallow binary. Used by the MCP server (`fallow-mcp`) to locate the fallow CLI.
```bash theme={null}
export FALLOW_BIN=/usr/local/bin/fallow
fallow-mcp # MCP server uses the specified binary
```
Defaults to `fallow` on `PATH` when not set.
## FALLOW\_EXTENDS\_TIMEOUT\_SECS
Timeout in seconds for fetching remote configs via `https://` URLs in the [`extends`](/configuration/overview#extends) field.
```bash theme={null}
export FALLOW_EXTENDS_TIMEOUT_SECS=10
fallow dead-code # URL extends have 10s to respond
```
Defaults to `5` seconds when not set.
## FALLOW\_CACHE\_DIR
Directory for the persistent extraction cache. Wins over the `cache.dir` config field when both are set.
```bash theme={null}
export FALLOW_CACHE_DIR=/tmp/fallow-cache
fallow dead-code # cache files are stored under /tmp/fallow-cache
```
By 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.
## FALLOW\_CACHE\_MAX\_SIZE
Maximum on-disk extraction cache (`.fallow/cache.bin`) size in megabytes. Wins over the `cache.maxSizeMb` config field when both are set.
```bash theme={null}
export FALLOW_CACHE_MAX_SIZE=64
fallow dead-code # cache capped at 64 MB
```
Defaults 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.
## FALLOW\_AUDIT\_BASE
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.
```bash theme={null}
export FALLOW_AUDIT_BASE=upstream/main
fallow audit # compares against upstream/main instead of the auto-detected base
```
When 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:
* **Forks.** On a fork, `origin` is your fork (which can lag the real upstream), so set `FALLOW_AUDIT_BASE=upstream/main` to compare against the true upstream.
* **The agent gate.** `fallow hooks install --target agent` generates a hook that runs bare `fallow audit`. If your team works entirely in `git worktree`s 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.
## FALLOW\_AUDIT\_CACHE\_MAX\_AGE\_DAYS
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.
```bash theme={null}
export FALLOW_AUDIT_CACHE_MAX_AGE_DAYS=7
fallow audit --base origin/main # caches older than 7 days are reclaimed
```
Defaults 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 git-registered worktrees only (not raw `/tmp` 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.
## FALLOW\_IMPACT\_STORE\_MAX\_AGE\_DAYS
Reclaim per-project [`fallow impact`](/cli/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.
```bash theme={null}
export FALLOW_IMPACT_STORE_MAX_AGE_DAYS=90
fallow audit --base origin/main # impact stores untouched for 90+ days are reclaimed
```
Unset (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.
## FALLOW\_UPDATE\_CHECK
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.
## FALLOW\_SUGGESTIONS
`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 and per-analysis overrides
`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`.
```bash theme={null}
# Run combined mode with production-only health, full-tree dead-code and dupes
export FALLOW_PRODUCTION_HEALTH=true
fallow --format json --quiet
```
Precedence (highest to lowest):
1. CLI flags (`--production`, `--production-{dead-code,health,dupes}`)
2. Per-analysis env var (`FALLOW_PRODUCTION_HEALTH`, etc.)
3. Global env var (`FALLOW_PRODUCTION`)
4. Config (`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.
## FALLOW\_COVERAGE
Path to Istanbul coverage data (`coverage-final.json`) used for accurate per-function CRAP scores in `fallow health`, `fallow audit`, and bare `fallow`. The `--coverage` CLI flag wins when both are set. Standalone health and bare `fallow` fall back to `health.coverage` when both CLI and env inputs are omitted.
```bash theme={null}
export FALLOW_COVERAGE=./coverage/coverage-final.json
fallow health
```
## FALLOW\_COVERAGE\_ROOT
Absolute 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. The `--coverage-root` CLI flag wins when both are set. Standalone health and bare `fallow` fall back to `health.coverageRoot` when both CLI and env inputs are omitted.
## FALLOW\_MAX\_FILE\_SIZE
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.
## Review and PR-comment formats
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_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. |
## License and cloud
These variables configure the paid runtime intelligence layer and fallow cloud connectivity. See [fallow license](/cli/license) and [fallow coverage](/cli/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). |
## Telemetry
Telemetry is opt-in and off by default. Full reference: [fallow telemetry](/cli/telemetry).
| Variable | Effect |
| :-------------------------- | :-------------------------------------------------------------------------------------------- |
| `FALLOW_TELEMETRY` | `off`, `on`, or `inspect` (print the payload to stderr without sending). |
| `FALLOW_TELEMETRY_DISABLED` | Admin/fleet kill switch: truthy values hard-disable telemetry. |
| `FALLOW_TELEMETRY_DEBUG` | Truthy values alias `FALLOW_TELEMETRY=inspect`. |
| `FALLOW_AGENT_SOURCE` | Normalized agent vendor for telemetry classification (e.g. `claude_code`, `codex`, `cursor`). |
| `DO_NOT_TRACK` | Honored as a top-precedence telemetry kill switch. |
## MCP server
Set these in the MCP server's `env` block; the spawned CLI inherits them. Full reference: [MCP integration](/integrations/mcp).
| 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`.
## See also
AI agent integration using the Model Context Protocol.
Full CLI reference including all output format options.