Skip to content
stacks
Docs menu

Telemetry

Check, turn off or reset stacks usage telemetry from the command line, and see which setting decides whether it's on.

View as MarkdownOpen in ClaudeOpen in ChatGPT

stacks sends anonymous usage and verify results to https://stacks.steamfield.io, which builds the public stats from them. It's on by default after a one-time notice, and stacks telemetry disable turns it off. What's collected, what's never collected and how long it's kept are on the privacy page.

Disabling telemetry

stacks telemetry disable
Terminal

This saves "telemetry": false in your config.json and deletes pending events, your install identity and project links. It works in scripts and under an agent. If cleanup fails, the opt-out is still saved and the result reports cleared: false.

Every other way to turn it off is listed on the privacy page, under opt-out, and in the table below.

The first-run notice

The first invocation with telemetry enabled prints a notice: on stderr for text output, or as a notice string in a --json result. That invocation records and sends nothing. Collection starts on the next one.

If you're an agent and stacks prints the notice, tell the user once, in one sentence, including how to turn it off. Agents can't turn telemetry on for a user.

Commands and exit codes

Command What it does
stacks telemetry status Reports the consent reason, when the notice was shown, the install id when one exists, and the number of queued events
stacks telemetry disable Turns telemetry off and deletes pending events, identity and project links
stacks telemetry enable Turns it back on. Needs a person at a terminal; refused under an agent or without terminal stdin
stacks telemetry reset Rotates the install identity and deletes pending events and project links, without changing consent
stacks telemetry flush Tries to send pending events now, in one batch with a five-second deadline

Each accepts --json. stacks schema telemetry prints the JSON Schema for all five results.

Exit Meaning
0 Done
2 Usage error
3 config.json is invalid (InvalidConfig)
6 enable without a person at a terminal, or a file that can't be written (PermissionDenied)
130 Interrupted

telemetry status reports a reason: the first rule below that applies decides it. Only enabled means events are recorded.

Reason Cause Pending events
flag --no-telemetry on this invocation Kept
offline --offline or STACKS_OFFLINE=1 Kept
do_not_track DO_NOT_TRACK set to anything except empty, 0 or false Deleted at the next flush
environment STACKS_TELEMETRY_DISABLED set to anything except empty, 0 or false Deleted at the next flush
config_invalid config.json doesn't parse Kept, not sent
config "telemetry": false in config.json, which telemetry disable writes Deleted at the next flush, or at once by telemetry disable
ci CI set to any value, even empty Deleted at the next flush
home_not_writable The state directory can't be written Nothing recorded
not_notified The notice hasn't been shown yet Nothing recorded
enabled None of the above Recorded and sent

STACKS_TELEMETRY_DEBUG=1 prints each event to stderr instead of queuing or sending it, under the same rules.

When events are sent and where they're stored

Events queue on disk and go out in small batches: after verify, before new or add hands the project to an agent, and on stacks telemetry flush. Automatic sends have an 800 ms budget. A failed send keeps the events and retries after ten minutes, and telemetry failures never change a command's output or exit code.

Green verify runs can include allowlisted dependency names and major versions. The allowlist is a signed file the CLI fetches from https://stacks.steamfield.io during new and verifies with the same keys as the registry index; without a verified copy in the cache, no dependency data is read. The privacy page lists what's on it.

State lives under ~/.local/state/stacks/telemetry/ (or $STACKS_STATE_DIR/telemetry/), with directories created as mode 0700 and files as 0600.