> ## 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 flags

> CLI reference for fallow flags. Detect feature flag patterns, environment variable gates, SDK calls, and config-based toggles across your codebase.

Detect feature flag patterns in your codebase. Fallow identifies environment variable flags (`process.env.FEATURE_*`), SDK calls from common providers (LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, Eppo), and config object patterns (opt-in). Reports flag locations, detection confidence, and cross-references with dead code findings.

<Tip>
  Use `fallow flags --format json` for structured output that agents and scripts can parse. Combine with `--top N` to focus on the most common flags.
</Tip>

```bash theme={null}
fallow flags
```

## Options

### Output

| Flag                    | Description                                                                                                                                                                               |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--top <N>`             | Show only the top N flags                                                                                                                                                                 |
| `-f, --format <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                                                                                                                                                                  |
| `--explain`             | Add metric explanations. In JSON format, adds a `_meta` object with descriptions and docs links.                                                                                          |
| `--summary`             | Print a one-line summary of flag counts at the end of the run. In JSON format, adds a `summary` counts object.                                                                            |

### Scoping

| Flag                     | Description                                                                                                 |
| :----------------------- | :---------------------------------------------------------------------------------------------------------- |
| `-r, --root <PATH>`      | Project root directory (default: current working directory)                                                 |
| `-c, --config <PATH>`    | Path to config file (default: auto-detected)                                                                |
| `-w, --workspace <NAME>` | Scope output to a single workspace package                                                                  |
| `--changed-since <REF>`  | Only report flags in files changed since a git ref                                                          |
| `--production`           | Production mode: exclude test/story/dev files                                                               |
| `--no-production`        | Force production mode off, overriding a project config's `production: true` (conflicts with `--production`) |

### Performance

| Flag            | Description                                               |
| :-------------- | :-------------------------------------------------------- |
| `--no-cache`    | Disable incremental caching (force full re-parse)         |
| `--threads <N>` | Number of parser threads (default: available parallelism) |
| `--performance` | Show pipeline timing breakdown                            |

### CI

| Flag                  | Description                                                                                                                                                                                                          |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ci`                | CI mode: equivalent to `--format sarif --fail-on-issues --quiet`                                                                                                                                                     |
| `--fail-on-issues`    | Exit with code 1 if flags are found                                                                                                                                                                                  |
| `--sarif-file <PATH>` | Write SARIF output to a file (in addition to `--format`)                                                                                                                                                             |
| `--group-by <MODE>`   | Group output by `owner` (CODEOWNERS), `directory` (first path component), `package` (workspace package), or `section` (GitLab CODEOWNERS `[Section]` headers). See [global flags](/cli/global-flags#grouped-output). |

### Regression

| Flag                                | Description                                                                    |
| :---------------------------------- | :----------------------------------------------------------------------------- |
| `--baseline <PATH>`                 | Compare against a previously saved baseline file                               |
| `--save-baseline <PATH>`            | Save current results as a baseline file                                        |
| `--fail-on-regression`              | Fail if flag 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 flag counts as a regression baseline                              |

## Detection categories

Fallow detects three categories of feature flag patterns:

| Category                       | What it finds                                           | Examples                                                                                                           |
| :----------------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------- |
| **Environment variable flags** | `process.env.*` checks used as feature gates            | `process.env.FEATURE_NEW_UI`, `process.env.ENABLE_DARK_MODE`                                                       |
| **SDK calls**                  | Feature flag SDK method calls from known providers      | LaunchDarkly `variation()`, Statsig `checkGate()`, PostHog `useFeatureFlagEnabled()`, Vercel Flags `flag({ key })` |
| **Config object patterns**     | Object property lookups used as boolean guards (opt-in) | `config.featureX`, `settings.enableNewFlow`                                                                        |

Each detected flag includes a confidence level indicating how certain fallow is that the pattern represents a feature flag.

## Configuration

Fallow ships with built-in detectors for the common providers and env-var conventions, so most projects need no configuration. If `fallow flags` reports `No feature flags detected` but your project does use flags, you are likely on an SDK or env prefix fallow does not recognize by default. Extend detection with the `flags` section in `.fallowrc.json`, `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`.

When you run `fallow flags` on full defaults and nothing is found, the CLI lists the built-in env prefixes and SDKs it scanned for, so you can tell a true negative from a missing detector.

### Schema

| Field                          | Type    | Default  | Description                                                                                                                 |
| :----------------------------- | :------ | :------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `flags.sdkPatterns`            | array   | `[]`     | Custom SDK call patterns, merged with the built-in providers.                                                               |
| `flags.sdkPatterns[].function` | string  | required | Function name to match (e.g. `"useFlag"`).                                                                                  |
| `flags.sdkPatterns[].nameArg`  | integer | `0`      | Zero-based index of the argument holding the flag name.                                                                     |
| `flags.sdkPatterns[].provider` | string  | (none)   | Optional provider label shown in output.                                                                                    |
| `flags.envPrefixes`            | array   | `[]`     | Extra `process.env.*` prefixes treated as flags, merged with the built-ins.                                                 |
| `flags.configObjectHeuristics` | boolean | `false`  | Detect property accesses on `feature`/`flag`/`toggle` objects as low-confidence flags. Opt-in (higher false-positive rate). |

Custom `sdkPatterns` and `envPrefixes` are merged with the built-in sets, never replace them.

### Examples

<CodeGroup>
  ```json PostHog theme={null}
  {
    "flags": {
      "sdkPatterns": [
        { "function": "isFeatureEnabled", "nameArg": 0, "provider": "PostHog" }
      ]
    }
  }
  ```

  ```json ConfigCat theme={null}
  {
    "flags": {
      "sdkPatterns": [
        { "function": "getValueAsync", "nameArg": 0, "provider": "ConfigCat" }
      ]
    }
  }
  ```

  ```json Vercel Flags + env prefixes theme={null}
  {
    "flags": {
      "sdkPatterns": [
        { "function": "flag", "nameArg": 0, "provider": "Vercel Flags" }
      ],
      "envPrefixes": ["NEXT_PUBLIC_FEATURE_", "MYAPP_ENABLE_"]
    }
  }
  ```

  ```json In-house SDK + config heuristics theme={null}
  {
    "flags": {
      "sdkPatterns": [
        { "function": "useMyFlag", "nameArg": 0, "provider": "InHouse" }
      ],
      "configObjectHeuristics": true
    }
  }
  ```
</CodeGroup>

<Note>
  Several providers shown above (PostHog, ConfigCat, Vercel Flags) are already built in, so these examples are illustrative. Reach for `sdkPatterns` when fallow does not recognize your wrapper function or you use an in-house SDK.
</Note>

## Examples

<CodeGroup>
  ```bash Basic analysis theme={null}
  # Detect all feature flags
  fallow flags

  # Show only the top 10 flags
  fallow flags --top 10
  ```

  ```bash CI integration theme={null}
  # JSON output for pipelines
  fallow flags --format json --quiet

  # SARIF for GitHub Code Scanning
  fallow flags --format sarif > flags.sarif

  # Compact format (one line per flag)
  fallow flags --format compact

  # Markdown for PR comments
  fallow flags --format markdown | gh pr comment --body-file -

  # CodeClimate for GitLab CI
  fallow flags --format codeclimate > gl-code-quality-report.json
  ```

  ```bash Scoping theme={null}
  # Only flags in changed files
  fallow flags --changed-since main

  # Scope to a workspace package
  fallow flags --workspace @app/core

  # Production code only
  fallow flags --production
  ```
</CodeGroup>

## JSON output

```json title="$ fallow flags --format json" theme={null}
{
  "schema_version": 3,
  "version": "3.3.0",
  "elapsed_ms": 116,
  "feature_flags": [],
  "total_flags": 0
}
```

### Key fields

| Field            | Type    | Description                             |
| :--------------- | :------ | :-------------------------------------- |
| `schema_version` | integer | JSON schema version (currently 3)       |
| `version`        | string  | Fallow version that produced the output |
| `elapsed_ms`     | integer | Analysis duration in milliseconds       |
| `feature_flags`  | array   | Detected feature flag patterns          |
| `total_flags`    | integer | Total number of detected flags          |

## MCP tool

The `feature_flags` MCP tool wraps `fallow flags --format json --quiet --explain`:

```json title="Example request" theme={null}
{
  "tool": "feature_flags",
  "arguments": {
    "top": 10
  }
}
```

The response always includes `_meta` explanatory metadata (the MCP wrapper enables `--explain` by default). Returns the same JSON envelope as the CLI.

See [MCP integration](/integrations/mcp) for setup instructions.

## See also

<CardGroup cols={3}>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/cli/dead-code">
    Cross-references feature flags with dead code findings.
  </Card>

  <Card title="Global flags" icon="sliders" href="/cli/global-flags">
    Flags available on every fallow command.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>