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

> CLI reference for fallow telemetry. Opt-in, off-by-default product telemetry for improving agent, CI, MCP, and editor workflows. Inspect the exact payload, enable, disable, or check status.

Manage opt-in product telemetry. Telemetry is **off by default** and exists to improve agent, CI, JSON, MCP, and editor workflows.

```bash theme={null}
fallow telemetry status
```

Fallow never collects repository names, file paths, package or dependency names, workspace names, source code, config values, environment variable names or values, raw command lines, raw errors, or stack traces. Hashing those values is not used as a workaround. See [Telemetry & privacy](/explanations/telemetry) for the full data and privacy contract.

To keep telemetry off everywhere, set `FALLOW_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`. To opt out on one machine, run `fallow telemetry disable`.

## Subcommands

### `status`

Show whether telemetry is on or off, what decided that (admin env var, shell env var, user config, or the default), the config file path, and the commands to change it.

```bash theme={null}
fallow telemetry status
```

### `enable` / `disable`

Turn telemetry on or off in the user-level config file. This requires an explicit human action; agents and wrappers must not enable telemetry automatically.

```bash theme={null}
fallow telemetry enable
fallow telemetry disable
```

Enabling is refused when `DO_NOT_TRACK` or `FALLOW_TELEMETRY_DISABLED` is set.

### `inspect`

Explain inspect mode, or print documented example payloads with field purposes.

```bash theme={null}
fallow telemetry inspect            # explain how to inspect a real run
fallow telemetry inspect --example  # print an example payload + field purposes
```

To see the exact payload a real command would send, **without sending it**, prefix the command with `FALLOW_TELEMETRY=inspect`:

```bash theme={null}
FALLOW_TELEMETRY=inspect fallow audit --format json --quiet
```

The inspected payload is printed to stderr; your command's normal output (including `--format json` on stdout) is untouched.

## How it is sent

When telemetry is enabled, Fallow sends one small JSON event per analysis run to `https://api.fallow.cloud/v1/telemetry/events` (override the host with `FALLOW_API_URL`). The request is an HTTPS POST with no authentication token and no cookies. The upload runs on a background thread, so it does not slow down your command, and network errors are ignored and never change your output or exit code. Fallow does not wait for the upload to finish, so the fastest runs and runs on slow networks often drop their event. Event counts are a rough, biased sample, not an exact count of usage.

## Precedence

```text theme={null}
DO_NOT_TRACK / FALLOW_TELEMETRY_DISABLED   (admin/fleet kill switch)
> FALLOW_TELEMETRY_DEBUG                     (forces inspect mode)
> FALLOW_TELEMETRY                           (per-shell override)
> CI: off unless FALLOW_TELEMETRY is set
> user telemetry config                      (fallow telemetry enable/disable)
> default: off
```

In CI, telemetry is off unless `FALLOW_TELEMETRY` is explicitly set in that CI environment. A developer's local `fallow telemetry enable` does not enable organization CI telemetry.

## Environment controls

| Variable                    | Description                                                                                      | Values                                                                           |
| :-------------------------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `FALLOW_TELEMETRY`          | Per-shell mode override                                                                          | `off`/`0`/`false`/`disabled`, `on`/`1`/`true`/`enabled`, `inspect`/`debug`/`log` |
| `FALLOW_TELEMETRY_DISABLED` | Admin/fleet 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 kill switch ([consoledonottrack.com](https://consoledonottrack.com)) | `1`, `true`, `yes`, `on`                                                         |
| `FALLOW_AGENT_SOURCE`       | Declare the calling agent for classification                                                     | see [Agent source](#agent-source)                                                |

## Agent source

If the user has already enabled telemetry, an agent or wrapper can tag the run with its own name, using one value from the fixed list below:

```bash theme={null}
export FALLOW_AGENT_SOURCE=codex
```

Accepted values: `codex`, `claude_code`, `cursor`, `copilot`, `opencode`, `aider`, `roo`, `windsurf`, `gemini` (aliases `gemini_cli` / `antigravity`), `cline`, `continue`, `zed`, `goose`, `other_known`, `unknown`, `none`. Hyphen aliases such as `claude-code` are normalized. Unrecognized values are ignored rather than uploaded. Agents not on the list (for example enterprise IDE assistants) are grouped under `other_known`. **Setting `FALLOW_AGENT_SOURCE` never enables telemetry by itself and uploads no codebase content.**

Fallow does not upload raw MCP client info, process names, parent process paths, editor or extension identifiers, environment variable names, model names, account or organization IDs, prompts, versions, or free-form vendor strings. When more than one agent environment is present at once, Fallow guesses which one is calling, and the guess can depend on the order it checks them. Set `FALLOW_AGENT_SOURCE` to name the agent yourself and get a reliable result.