From 904b843fee55aaa39b4c0f53582059f673b1b9da Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Thu, 30 Apr 2026 10:56:19 +0200 Subject: [PATCH] docs(coding-agent): clarify telemetry update checks --- packages/coding-agent/README.md | 14 +++++++++++--- packages/coding-agent/docs/settings.md | 8 +++++++- packages/coding-agent/docs/usage.md | 5 +++-- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md index bbb59fd2..c034bb88 100644 --- a/packages/coding-agent/README.md +++ b/packages/coding-agent/README.md @@ -277,7 +277,14 @@ Use `/settings` to modify common options, or edit JSON files directly: See [docs/settings.md](docs/settings.md) for all options. -To opt out of anonymous install/update telemetry tied to changelog detection, set `enableInstallTelemetry` to `false` in `settings.json`, or set `PI_TELEMETRY=0`. +### Telemetry and update checks + +Pi has two separate startup features: + +- **Update check:** fetches `https://pi.dev/api/latest-version` to check whether a newer Pi version exists. Disable it with `PI_SKIP_VERSION_CHECK=1`. Disabling update checks only turns off this check. +- **Install/update telemetry:** after first install or a changelog-detected update, sends an anonymous version ping to `https://pi.dev/api/report-install`. Opt out by setting `enableInstallTelemetry` to `false` in `settings.json`, or by setting `PI_TELEMETRY=0`. This does not disable update checks; Pi may still contact `pi.dev` for the latest version unless update checks are disabled or offline mode is enabled. + +Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry. --- @@ -615,8 +622,9 @@ pi --thinking high "Solve this complex problem" |----------|-------------| | `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.pi/agent`) | | `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) | -| `PI_SKIP_VERSION_CHECK` | Skip version check at startup | -| `PI_TELEMETRY` | Override install telemetry. Use `1`/`true`/`yes` to enable or `0`/`false`/`no` to disable | +| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry | +| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request | +| `PI_TELEMETRY` | Override install/update telemetry. Use `1`/`true`/`yes` to enable or `0`/`false`/`no` to disable. This does not disable update checks | | `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) | | `VISUAL`, `EDITOR` | External editor for Ctrl+G | diff --git a/packages/coding-agent/docs/settings.md b/packages/coding-agent/docs/settings.md index 5a999392..5e39646b 100644 --- a/packages/coding-agent/docs/settings.md +++ b/packages/coding-agent/docs/settings.md @@ -41,13 +41,19 @@ Edit directly or use `/settings` for common options. | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) | | `quietStartup` | boolean | `false` | Hide startup header | | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates | -| `enableInstallTelemetry` | boolean | `true` | Send an anonymous version/update ping after changelog-detected updates | +| `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks | | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` | | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` | | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) | | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) | | `showHardwareCursor` | boolean | `false` | Show terminal cursor | +### Telemetry and update checks + +`enableInstallTelemetry` only controls the anonymous install/update ping to `https://pi.dev/api/report-install`. Opting out of telemetry does not disable update checks; Pi can still fetch `https://pi.dev/api/latest-version` to look for the latest version. + +Set `PI_SKIP_VERSION_CHECK=1` to disable the Pi version update check. Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry. + ### Warnings | Setting | Type | Default | Description | diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.md index 1b43783d..9de6ac59 100644 --- a/packages/coding-agent/docs/usage.md +++ b/packages/coding-agent/docs/usage.md @@ -261,8 +261,9 @@ pi --tools read,grep,find,ls -p "Review the code" |----------|-------------| | `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.pi/agent` | | `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths | -| `PI_SKIP_VERSION_CHECK` | Skip version check at startup | -| `PI_TELEMETRY` | Override install telemetry: `1`/`true`/`yes` or `0`/`false`/`no` | +| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry | +| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request | +| `PI_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks | | `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported | | `VISUAL`, `EDITOR` | External editor for Ctrl+G |