> ## 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` (`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`](/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; during [`fallow audit-cache prune`](/cli/audit#audit-cache-prune), the `--max-age-days` flag wins over this variable.
```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 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`](/cli/audit#audit-cache-prune).
## 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`. 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.
```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. 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.
## 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_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. |
## 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.