telemetry¶

mytool telemetry <status | enable | disable | reset>

Feature: Telemetry. Passthrough subtree — --output must appear after the word telemetry. There is no default subcommand.

Where consent is stored¶

<config_dir>/consent.toml, with <config_dir> derived exactly as for config:

telemetry status always prints the resolved path, so you never have to guess.

How the effective state is decided¶

Four steps, each short-circuiting:

1. Compile-time off. If the tool did not compile telemetry in, the telemetry subtree is not registered at all and none of this is reachable from the CLI.
2. Consent file. enabled → enabled, disabled → disabled. unset or no file falls through.
3. <TOOLNAME>_TELEMETRY environment variable, upper-cased from ToolMetadata::name. 1, true or on (case-insensitive) → enabled; 0, false or off → disabled. Any other value is ignored and falls through.
4. Default: disabled. Opt-in is the standing rule.

The env variable is only consulted when the consent file has nothing to say. Writing consent with enable or disable therefore makes the variable inert until you reset.

The env-var name is derived, not sanitised¶

The variable name is ToolMetadata::name.to_uppercase() with _TELEMETRY appended. A tool named my-tool looks for MY-TOOL_TELEMETRY, which most shells will not let you export without env tricks. Tools that want a usable override should keep their name free of hyphens and other punctuation.

telemetry status¶

Prints one row describing the current decision.

$ mytool telemetry status
 state | source  | decided_at | policy   | consent_file
-------+---------+------------+----------+-----------------------------------
 unset | default | -          | Disabled | /home/you/.config/mytool/consent.toml

Honours --output json.

telemetry enable¶

Writes enabled plus a timestamp to the consent file, then prints the tool's privacy notice — ToolMetadata::telemetry_notice when set, otherwise a generic message that also says no notice was configured. Prints the consent file path.

enable refuses under CI=true¶

telemetry enable refused under CI=true

with help interactive opt-in only — a CI=true environment may not flip it on. Consent to being measured is something a person gives; a build pipeline flipping it on for every job that inherits the variable is not consent.

The check is an exact string comparison against CI=true. CI=1, CI=yes and CI=TRUE do not trigger the refusal. If your pipeline sets one of those and you want the refusal, set CI=true as well.

telemetry disable¶

Writes disabled plus a timestamp. Never refused, in CI or anywhere else — opting out is always allowed.

telemetry reset¶

Removes the consent file, returning the state to unset and re-enabling the environment-variable override. Idempotent: resetting when there is no file succeeds.