A CLI telemetry page should state why you collect data, list each field, name what you never collect, give a retention period, show how to inspect events, and give a one-line opt-out. Public examples from Homebrew and Next.js cover most of these points.
The six sections
- Purpose. Homebrew says its data helps maintainers prioritise widely used packages, commands and platforms. It adds that analytics must not replace technical evidence or maintainer judgement. Saying what the data will not be used for builds more trust than a vague benefit.
- Fields collected. List them by event type. Homebrew separates package events, build-error events and command events, and says command events keep option names after option values have been removed.
- Exclusions. Next.js states it does not collect environment variables, file paths, file contents, logs or serialized JavaScript errors. Homebrew says build-error events do not include build logs or exception details, and the payload has no user identifier or IP address field.
- Retention. Homebrew states 365 days for events in its database. If you do not have a number, pick one before you publish the page.
- Inspection. Name the debug switch. Next.js and Homebrew each have one.
- Opt out. Homebrew documents
brew analytics offand an environment variable. Next.js documents atelemetry disablesubcommand and a status command.
Wording to avoid
Words like anonymous and aggregate carry weight, so use them when true. Homebrew says its payload has no user identifier, which is a specific, checkable claim. Next.js says its data is anonymous and not traceable to the source. If your event includes a random install ID that persists, the data is only pseudonymous, and a reviewer will notice.
Also avoid promising never to change the list. Say instead where changes are announced.
A short template
| Section | One line to write |
|---|---|
| Purpose | We collect X to decide Y. We do not use it for Z. |
| Fields | A table of event name, fields, example value |
| Never collected | Paths, file contents, environment values, tokens |
| Retention | N days, then deleted |
| Inspect | Set VARIABLE=1 to print events without sending |
| Opt out | Run tool telemetry off or set VARIABLE=1 |
Keep the page honest
Homebrew's page points to its implementation files and says they are authoritative if the page and the code disagree. That is a good habit. A telemetry page that drifts from the code is worse than none, because readers trust it. Add the page to your release checklist so any new event updates it in the same pull request.
What reviewers will ask next
Expect questions on where the data goes, which processor hosts it, and whether a third-party analytics library is in the binary. Have those answers ready. They belong on the same page.
Quick check
Is it enough to say the data is anonymous?
Not on its own. Say which identifiers are absent and which fields are present. A specific claim can be checked. A label cannot.
Do we need a retention period for a small tool?
Yes. Choose one, publish it, and delete on schedule. Reviewers ask about it in almost every vendor questionnaire.
Safeguard's free scan at gold.safeguard.sh/scan can show which packages your CLI ships, which helps answer the third-party library question.
Sources
Last reviewed: 19 October 2026.
