> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Privacy & Telemetry

> ubx collects anonymous, opt-in usage statistics. No source code, resource names, secrets, or personally identifiable information is ever transmitted.

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:

| Field          | Example                  | Description                                                       |
| -------------- | ------------------------ | ----------------------------------------------------------------- |
| `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_code`    | `0`                      | `0` for success; only successful invocations send events in v1    |
| `duration_ms`  | `1240`                   | Wall-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](#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:

| Platform | Source identifier                       |
| -------- | --------------------------------------- |
| macOS    | `IOPlatformUUID` from `ioreg`           |
| Linux    | `/etc/machine-id`                       |
| Windows  | `MachineGuid` from the Windows registry |
| Fallback | System 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.

### First-run consent prompt

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:

```bash theme={"theme":"css-variables"}
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`:

```yaml theme={"theme":"css-variables"}
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

```bash theme={"theme":"css-variables"}
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

```bash theme={"theme":"css-variables"}
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):

| Priority    | Setting                                     | Effect                    |
| ----------- | ------------------------------------------- | ------------------------- |
| 1 (highest) | `UBX_TELEMETRY=0`                           | Force disable             |
| 2           | `UBX_TELEMETRY=1`                           | Force enable              |
| 3           | `ubx.yaml` `telemetry.enabled: false`       | Disable                   |
| 4           | `ubx.yaml` `telemetry.enabled: true`        | Enable                    |
| 5           | `~/.ubx/telemetry-consent` `enabled: false` | Disable                   |
| 6           | `~/.ubx/telemetry-consent` `enabled: true`  | Enable                    |
| 7 (lowest)  | no consent file                             | Disable (opt-in required) |

***

## Override endpoint

Override the telemetry endpoint for testing or self-hosted deployments:

```bash theme={"theme":"css-variables"}
UBX_TELEMETRY_ENDPOINT=https://your.server/v1/event ubx plan
```

Or in `ubx.yaml`:

```yaml theme={"theme":"css-variables"}
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`.

***

## Consent file location

```
~/.ubx/telemetry-consent
```

The file is a JSON object with a single field:

```json theme={"theme":"css-variables"}
{"enabled": true}
```

or

```json theme={"theme":"css-variables"}
{"enabled": false}
```

To reset the consent decision and see the prompt again on next run, delete the file:

```bash theme={"theme":"css-variables"}
rm ~/.ubx/telemetry-consent
```

***

## CI / automated environments

In CI pipelines, telemetry should be either explicitly disabled or explicitly enabled:

```bash theme={"theme":"css-variables"}
# 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.