Skip to main content
ubx can collect anonymous usage statistics to help the team understand how the tool is used and where to invest in improvements. Telemetry is disabled by default and requires an explicit opt-in.

​
What is collected

Every CLI invocation sends a single event when telemetry is enabled:
FieldExampleDescription
event"ubx_command"Always "ubx_command" — the event type
command"plan"Top-level subcommand (plan, apply, validate, …)
subcommand"apply"Second-level subcommand, e.g. workspace apply; empty otherwise
ubx_version"v0.1.0"The ubx CLI version that ran
os"darwin"Operating system (darwin, linux, windows)
arch"arm64"CPU architecture (arm64, amd64)
exit_code00 for success; only successful invocations send events in v1
duration_ms1240Wall-clock time from start to completion (milliseconds)
providers["aws"]Provider names in use in the current project
anonymous_id"a3f9b2…"SHA256 hash of the machine ID — see Anonymous ID
sent_at"2026-06-29T14:00:00Z"RFC 3339 UTC timestamp of the event

​
What is never collected

The following information is never sent, regardless of configuration:
  • Source code or .iac file contents
  • Resource names, attribute values, or infrastructure topology
  • Stack output values or secret values
  • File paths or directory names
  • IP addresses
  • Cloud account IDs or ARNs
  • Git commit messages or branch names
  • Any personally identifiable information (PII)

​
Anonymous ID

The anonymous_id field is a SHA256 hash of a platform-specific machine identifier:
PlatformSource identifier
macOSIOPlatformUUID from ioreg
Linux/etc/machine-id
WindowsMachineGuid from the Windows registry
FallbackSystem hostname
The raw identifier is never transmitted. Only the SHA256 hex digest (64 lowercase characters) is included in the event payload. Two ubx installations on the same machine produce the same anonymous_id; two machines always produce different values.

​
Disabled by default

Telemetry is never enabled automatically. ubx requires explicit opt-in through one of the mechanisms below. On the first invocation of ubx (when ~/.ubx/telemetry-consent does not yet exist), ubx shows a one-time prompt: 
  ubx collects anonymous usage statistics to help improve the product.
  No source code, secrets, or personal data are ever collected.
  Learn more: https://docs.ubiquex.io/telemetry

  Enable telemetry? [y/N]
  • Typing y or yes opts in and writes {"enabled": true} to ~/.ubx/telemetry-consent.
  • Any other input (or pressing Enter for the default N) declines and writes {"enabled": false}.
The consent file is written on first run and never shown again on subsequent invocations.

​
Non-interactive environments

When stdin is not a TTY (CI pipelines, Docker, piped input), the prompt is never shown. The consent file is written automatically with enabled: false. Telemetry remains disabled unless UBX_TELEMETRY=1 is set explicitly.

​
--no-telemetry-prompt flag

Pass --no-telemetry-prompt to any ubx command to skip the consent prompt on that run. The consent file is written with enabled: false if it does not already exist: 
ubx plan --no-telemetry-prompt
This flag is useful in setup scripts that run in interactive environments but should not pause for a prompt.

​
Opt-in via ubx.yaml

Enable telemetry at the project level by adding telemetry.enabled: true to ubx.yaml: 
telemetry:
  enabled: true
  endpoint: https://telemetry.ubiquex.io/v1/event  # optional override
When enabled: true is set, telemetry fires even if the user’s ~/.ubx/telemetry-consent has enabled: false — the project-level setting takes precedence. This is intended for teams that want to collect aggregate usage across all developers and CI runs.

​
Opt-in via environment variable

UBX_TELEMETRY=1 ubx plan
UBX_TELEMETRY=1 enables telemetry for a single invocation. It overrides both ubx.yaml and the consent file.

​
Force disable

UBX_TELEMETRY=0 ubx plan
UBX_TELEMETRY=0 disables telemetry for a single invocation, overriding all other settings including ubx.yaml and the consent file.

​
Priority order

When multiple settings conflict, the following priority applies (highest wins):
PrioritySettingEffect
1 (highest)UBX_TELEMETRY=0Force disable
2UBX_TELEMETRY=1Force enable
3ubx.yaml telemetry.enabled: falseDisable
4ubx.yaml telemetry.enabled: trueEnable
5~/.ubx/telemetry-consent enabled: falseDisable
6~/.ubx/telemetry-consent enabled: trueEnable
7 (lowest)no consent fileDisable (opt-in required)

​
Override endpoint

Override the telemetry endpoint for testing or self-hosted deployments: 
UBX_TELEMETRY_ENDPOINT=https://your.server/v1/event ubx plan
Or in ubx.yaml: 
telemetry:
  enabled: true
  endpoint: https://your.server/v1/event
The env var takes precedence over the ubx.yaml value.

​
Transmission behaviour

  • Events are sent in a background goroutine — telemetry never blocks the CLI.
  • The HTTP request has a 2-second timeout. If the endpoint is unreachable, the error is silently dropped.
  • Events are never retried on failure.
  • No buffering or batching — one HTTP POST per invocation when telemetry is enabled.
  • The default endpoint is https://telemetry.ubiquex.io/v1/event.
~/.ubx/telemetry-consent
The file is a JSON object with a single field: 
{"enabled": true}
or 
{"enabled": false}
To reset the consent decision and see the prompt again on next run, delete the file: 
rm ~/.ubx/telemetry-consent

​
CI / automated environments

In CI pipelines, telemetry should be either explicitly disabled or explicitly enabled: 
# Disable telemetry in CI (recommended default)
export UBX_TELEMETRY=0

# Enable telemetry in CI (opt-in for aggregate usage tracking)
export UBX_TELEMETRY=1
If neither env var is set and no consent file exists, ubx detects the non-TTY environment and writes a {"enabled": false} consent file silently. No prompt is shown, no data is sent.