Product Telemetry and Privacy

Open Knowledge collects bounded product telemetry to measure installation, activation, useful command activity, daily activity, and sanitized errors.

CLI telemetry is enabled by default. The CLI prints a disclosure before it sends the first event. Telemetry commands do not send events. JSON error mode waits for a prior telemetry disclosure. Installer preflight and continuous integration do not send telemetry.

CLI controls

okn telemetry status
okn telemetry show-payload
okn telemetry disable
okn telemetry enable
okn --no-telemetry <command>

Put --no-telemetry before the command. This option disables telemetry for the current command and future commands. It also deletes the random installation ID.

Set DO_NOT_TRACK=1 or OPENKNOWLEDGE_TELEMETRY=off for a process-level override. These variables do not change the saved preference.

The CLI stores its preference under the operating system user configuration directory. The file is openknowledge/telemetry.json and uses user-only access.

Collected data

CLI events can include only these fields:

• Random installation and event IDs
• CLI version, operating system, and architecture
• Allowlisted command and subcommand names
• Success, usage error, or command failure
• A coarse duration bucket
• First command, successful setup, first meaningful use, and daily activity

cli_first_command records the first observed CLI run. Setup and meaningful-use events require successful commands.

Excluded data

CLI telemetry envelopes do not contain:

• Command arguments, paths, file names, URLs, queries, or repository names
• Knowledge content, command output, error messages, or agent transcripts
• User accounts, email addresses, hostnames, or machine-derived identifiers
• IP addresses or raw user-agent strings

Delivery

The CLI sends one bounded JSON envelope after a command finishes. Delivery uses a short timeout. A delivery failure does not change output or exit status.

The default endpoint is https://openknowledge.sh/api/telemetry. Set OPENKNOWLEDGE_TELEMETRY_ENDPOINT to override the endpoint for a process. The CLI sends its bounded envelope without a PostHog project token or SDK.

The separate openknowledge-website project owns the first-party relay and its upstream configuration. This repository does not build or deploy that service. Website consent controls and analytics also belong to that project.

Session observation is a separate local feature. --observe remains opt-in and does not change product telemetry.

Local runtime usage events

Runtime usage events are separate from first-party product telemetry. They are disabled by default and stay under the configured runtime state_dir. The CLI does not send these events to the first-party telemetry relay.

Runtime usage events use [serve.usage_events] settings. Product telemetry preferences and okn telemetry commands do not control these settings. See the runtime command for the local event fields, privacy defaults, and retention setting.

When runtime usage events are enabled, retrieval responses can return an opaque local usage event ID. POST <route>/_feedback uses that ID to create a private grounded feedback event under <state_dir>/feedback.

Feedback events bind the original query fingerprint, generation, outcome, and selected evidence. They do not copy raw query text. Open Knowledge does not send usage or feedback events to the first-party telemetry relay. The usage event retention setting also controls feedback JSONL retention.