Skip to content

PRIVACY.md

Latest commit

 

History

History
119 lines (87 loc) · 4.99 KB

PRIVACY.md

File metadata and controls

119 lines (87 loc) · 4.99 KB
Raw

Telemetry & Privacy

The polylane CLI sends anonymous usage telemetry by default. This document is the authoritative source of truth for what we collect, what we don't, and how to opt out. The polylane telemetry status command prints the same information live.

Quick links

  • Disable: polylane telemetry disable (persists to ~/.polylane/config.json)
  • Inspect: polylane telemetry status
  • Re-enable: polylane telemetry enable

What we collect

One event per command invocation, fired after the command finishes (success or failure):

Identity

Field Example Purpose
installId "f2f3b5a4-..." Anonymous per-install UUID, generated once on first run
sessionId "31bbf6df-..." Per-process UUID, correlates events within one invocation
workspaceId "ws_xxx..." Tenant attribution (not user)
authMethod "oauth" | "api-key" | null Credential class — never the token itself

CLI + install

Field Example Purpose
cli.version "0.1.0" CLI release in use
cli.installSource "brew" npm / brew / curl / bun / dev / unknown
cli.ref "gh-readme" Optional referral slug the website installer recorded in ~/.polylane/ref (validated against ^[a-zA-Z0-9._-]{1,64}$, omitted when absent)

Runtime

Field Example Purpose
runtime.node "22.14.0" Node version
runtime.os "darwin" Platform
runtime.osRelease "23.5.0" Kernel / OS release version
runtime.arch "arm64" CPU architecture
runtime.ci / runtime.ciName true / "GitHub Actions" CI detection + provider
runtime.tty / runtime.stderrTty true / true Interactive vs piped
runtime.shell "zsh" Shell basename
runtime.terminal "iTerm.app" TERM_PROGRAM
runtime.language "en" Two-letter from $LANG (never the full locale)
runtime.timezone "America/New_York" IANA timezone
runtime.cpuCount 10 Logical CPU count
runtime.cpuModel "Apple M1 Pro" First CPU model string
runtime.cpuSpeedMhz 3228 First CPU clock speed
runtime.totalMemoryMb 32768 Total system memory (MB)
runtime.memoryRssBytes 52428800 Process RSS at event time

Invocation

Field Example Purpose
command "case investigate" Which verb was used
flags ["output", "quiet", "stream"] Flag names only — never values
positionalArgCount 2 Number of positional args (never the values)
outputFormat "json" Resolved text/json
modes { quiet: true, verbose: false, ... } Mode flags state
durationMs 1234 Total command duration
bootMs 42 Process startup cost
http.requestCount / http.totalMs 3 / 820 API calls made + total HTTP time

Outcome

Field Example Purpose
exitCode 0 Success / usage / auth / etc.
error.code / error.category 3 / "AUTH" Category only, on failures
error.httpStatus 401 Parsed from API error message when present (no message body shipped)

Sequence

Field Example Purpose
sequence.runCount 42 Total invocations on this install (incl. this one)
sequence.daysSinceInstall 7 Cohort retention
sequence.previousCommand "workspace use" Funnel analysis

What we never collect

  • Flag values, positional argument values, prompts
  • Credentials, tokens, passwords, OAuth scopes
  • User IDs, emails, names
  • File paths, stdin contents, command output
  • Full error messages or stack traces (only the category and HTTP status)

Where events go

POST https://<api-domain>/v1/telemetry/cli. Override with POLYLANE_TELEMETRY_ENDPOINT=<url>.

Requests are fire-and-forget with a 2-second timeout and silently fail on network / server errors. Telemetry cannot break a command.

How to opt out

Any of these switches telemetry off:

Method Scope
polylane telemetry disable Persistent — writes telemetry: false to ~/.polylane/config.json
polylane config set --key telemetry --value false Same (alt command)
POLYLANE_TELEMETRY=0 (or false, no, off) Per-invocation / per-shell
DO_NOT_TRACK=1 Universal — respects the DO_NOT_TRACK standard

Precedence: DO_NOT_TRACK > POLYLANE_TELEMETRY env var > config file > default (on).

When disabled, no events are sent. The install ID stays on disk (so re-enabling works), but nothing leaves your machine.

First-run notice

The first time you run a command with telemetry enabled, the CLI writes a one-line notice to stderr pointing you at this document. It records that the notice has been shown in ~/.polylane/telemetry.json and does not repeat.

State files

  • ~/.polylane/telemetry.json — install ID + first-run notice flag
  • ~/.polylane/config.json — telemetry: false (if opted out)

Both are mode 0600.