relate telemetry

The relate telemetry command with on, off and status, what each prints, the config file it writes, the environment layers that outrank it, and exit codes.

cli

relate telemetry on|off|status manages the anonymous usage metrics the relate CLI sends, its telemetry The anonymous usage metrics the relate CLI sends: on by default, off with DO_NOT_TRACK=1, RELATE_TELEMETRY=0 or relate telemetry off. Read more in the glossary. off and on write the setting to config.json in the user's config directory and print the file's path; status prints whether usage metrics are on and which layer decided it. The setting is the third of four layers: DO_NOT_TRACK and RELATE_TELEMETRY in the environment outrank it. Usage metrics are on by default. What the events hold, and what they never hold, is on Privacy and telemetry.

Synopsis

relate telemetry on|off|status

Action	Does	Prints on stdout
`on`	Writes `{"telemetry":true}` to `config.json`	`telemetry enabled (<path to config.json>)`
`off`	Writes `{"telemetry":false}` to `config.json`	`telemetry disabled (<path to config.json>)`
`status`	Reads the layers; writes nothing	`<enabled\|disabled> (<layer>)`, the layer being `DO_NOT_TRACK`, `RELATE_TELEMETRY`, `config file` or `default`

Exactly one action is required, in lowercase. The command takes no flags beyond --help.

Where the setting lives

on and off write one file, created with mode 0600 on Unix:

Environment	File
`XDG_CONFIG_HOME` set to an absolute path	`$XDG_CONFIG_HOME/relate/config.json`
Otherwise, with `HOME` set	`$HOME/.config/relate/config.json`
Otherwise, with `APPDATA` set to an absolute path	`$APPDATA/relate/config.json`
Otherwise, with `USERPROFILE` set to an absolute path	`$USERPROFILE/.config/relate/config.json`
None of them	No file: exit code 1 with `Error: telemetry: cannot resolve a config directory (set $XDG_CONFIG_HOME, $HOME, $APPDATA, or $USERPROFILE)`

The same directory holds state.json, which holds the random install ID and the first-run notice flag. Any run with usage metrics on, relate telemetry off included, creates it when it is missing and sends one RELATE-CLI_COMMAND event (command: telemetry, action: off) before the new setting takes effect. A run with DO_NOT_TRACK=1 set writes neither.

Which layer decides

The first layer that matches decides, and status names it:

Order	Layer	Turns usage metrics off	Turns them on	`status` prints
1	`DO_NOT_TRACK`	`1` or `true`	—	`disabled (DO_NOT_TRACK)`
2	`RELATE_TELEMETRY`	`0`, `false` or `off`	`1`, `true` or `on`	`disabled (RELATE_TELEMETRY)` or `enabled (RELATE_TELEMETRY)`
3	`config.json`, written by `relate telemetry off` and `on`	`false`	`true`	`disabled (config file)` or `enabled (config file)`
4	Default	—	on	`enabled (default)`

Both variables are read trimmed and case-insensitive (DO_NOT_TRACK=TRUE and RELATE_TELEMETRY=OFF count). DO_NOT_TRACK=0 is not an opt-out and passes the decision to the next layer, and so does a RELATE_TELEMETRY value other than those six, in any case. relate telemetry on writes the file even while DO_NOT_TRACK=1 is set, and the variable still wins. relate telemetry off does not change the environment, so a RELATE_TELEMETRY=1 in it still turns usage metrics on.

The first-run notice and the events

The first statement run with usage metrics on prints relate collects anonymous usage metrics; disable anytime: relate telemetry off on stderr, once per install. A run with usage metrics off prints no notice, sends nothing and writes no state.json. The setting a run reads is the one in force when it starts, so relate telemetry off itself still sends its own command event when usage metrics were on. The four events, their properties, the install ID and the delivery are listed on Privacy and telemetry; the agent and minimal builds from source contain no usage metrics code and have no telemetry command.

Errors and exit codes

Exit code	When	Message on stderr
0	The action ran	None
1	`on` or `off` found no config directory, or could not write the file	`Error: telemetry: cannot resolve a config directory (set $XDG_CONFIG_HOME, $HOME, $APPDATA, or $USERPROFILE)`, or `Error: telemetry: writing <path to config.json>: <reason>`
2	No action	`Error: telemetry requires an action (on, off, or status)`
2	An unknown action, or a second argument	`Error: unexpected argument to telemetry: <argument>`

Each exit 2 also prints the usage line and Run 'relate telemetry --help' for more information.

Examples

These examples run with DO_NOT_TRACK=1 set, in a fresh home directory shown as <home>, so no command here sends anything. status names the environment layer, off writes the file, and env -u DO_NOT_TRACK runs one command without the variable to show the file's layer underneath:

relate telemetry status
relate telemetry off
env -u DO_NOT_TRACK relate telemetry status

disabled (DO_NOT_TRACK)
telemetry disabled (<home>/.config/relate/config.json)
disabled (config file)

The file holds one key:

cat "$HOME/.config/relate/config.json"
echo

{"telemetry":false}

RELATE_TELEMETRY outranks the file:

env -u DO_NOT_TRACK RELATE_TELEMETRY=0 relate telemetry status

disabled (RELATE_TELEMETRY)

With XDG_CONFIG_HOME set to an absolute path, the file goes under it:

mkdir -p "$PWD/config"
XDG_CONFIG_HOME="$PWD/config" relate telemetry off

The working directory is shown as <dir>:

telemetry disabled (<dir>/config/relate/config.json)

A missing or unknown action is a usage error:

relate telemetry
echo "exit=$?"
relate telemetry maybe
echo "exit=$?"

Error: telemetry requires an action (on, off, or status)
Usage: relate telemetry on|off|status
Run 'relate telemetry --help' for more information.
exit=2
Error: unexpected argument to telemetry: maybe
Usage: relate telemetry on|off|status
Run 'relate telemetry --help' for more information.
exit=2