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

# Telemetry

> Understand CLI telemetry, what data is collected, and how to disable it.

# Telemetry

The Nexudus CLI collects anonymous usage data to help us improve the tool and understand how it's being used. Telemetry is **enabled by default** but can be **completely disabled** at any time.

## What data is collected?

The CLI collects the following information for each command execution:

| Field           | Description                      | Example                                 |
| --------------- | -------------------------------- | --------------------------------------- |
| `timestamp`     | When the command ran (UTC)       | `2026-04-22T10:30:45.123Z`              |
| `command`       | Full command path                | `coworkers.list`                        |
| `entity`        | Entity type                      | `coworkers`                             |
| `operation`     | Operation performed              | `list`, `create`, `delete`, etc.        |
| `success`       | Whether the command succeeded    | `true` or `false`                       |
| `durationMs`    | How long the command took        | `245` (milliseconds)                    |
| `errorCategory` | Error classification (if failed) | `auth`, `not_found`, `validation`, etc. |
| `cliVersion`    | CLI version                      | `1.0.0`                                 |
| `os`            | Operating system                 | `win`, `mac`, `linux`, or `unknown`     |

**No sensitive data is collected.** Credentials, API responses, entity details, or business information are never sent.

## Disable telemetry

Telemetry can be disabled using a single command:

```bash theme={null}
nexudus config set telemetry off
```

To verify telemetry is disabled:

```bash theme={null}
nexudus config get telemetry
```

Output:

```
telemetry = off
```

Once disabled, all telemetry events are discarded immediately and no data is sent anywhere.

## Re-enable telemetry

To re-enable telemetry:

```bash theme={null}
nexudus config set telemetry on
```

Or simply remove the setting:

```bash theme={null}
nexudus config unset telemetry
```

## Configuration storage

Your telemetry preference is stored in your personal configuration file at:

| Operating system | Path                                 |
| ---------------- | ------------------------------------ |
| Windows          | `%UserProfile%\.nexudus\config.json` |
| macOS            | `~/.nexudus/config.json`             |
| Linux            | `~/.nexudus/config.json`             |

You can also edit this file directly. To disable telemetry, add:

```json theme={null}
{
  "telemetry": "off"
}
```

## Where is data sent?

When telemetry is enabled, data is sent to **Logz.io**, a secure, third-party analytics platform. The connection uses HTTPS with a 3-second timeout. If the network request fails for any reason, the CLI silently continues — telemetry errors never break your workflow.

## Debug mode

For troubleshooting and local testing, you can enable debug mode to save telemetry events to a local file:

```bash theme={null}
nexudus config set telemetry-debug on
```

When debug mode is enabled, telemetry events are saved to:

| Operating system | Path                                     |
| ---------------- | ---------------------------------------- |
| Windows          | `%UserProfile%\.nexudus\telemetry.jsonl` |
| macOS            | `~/.nexudus/telemetry.jsonl`             |
| Linux            | `~/.nexudus/telemetry.jsonl`             |

Each event is stored as a single line of JSON (JSONL format). Example:

```jsonl theme={null}
{"timestamp":"2026-04-22T10:30:45.123Z","command":"coworkers.list","entity":"coworkers","operation":"list","success":true,"durationMs":245,"errorCategory":null,"cliVersion":"1.0.0","os":"win","type":"nexudus-cli"}
{"timestamp":"2026-04-22T10:31:12.456Z","command":"coworkers.get","entity":"coworkers","operation":"get","success":false,"durationMs":512,"errorCategory":"not_found","cliVersion":"1.0.0","os":"win","type":"nexudus-cli"}
```

To disable debug mode:

```bash theme={null}
nexudus config set telemetry-debug off
```

<Note>Debug mode only saves data locally. It does not affect whether data is sent to Logz.io. To disable remote telemetry entirely, use `nexudus config set telemetry off`.</Note>

## AI agent invocations

When the CLI is used by AI assistants (like GitHub Copilot or Claude), additional context fields are included in telemetry:

| Field     | Description                                   | Example                   |
| --------- | --------------------------------------------- | ------------------------- |
| `isAgent` | Whether invoked by an AI assistant            | `true` or `false`         |
| `caller`  | Name of the AI assistant                      | `copilot`, `claude`, etc. |
| `traceId` | Unique ID to correlate commands within a task | `abc123-def456-ghi789`    |
| `intent`  | One-line summary of the user's request        | `Find all active members` |
| `attempt` | Retry attempt number                          | `1`, `2`, etc.            |

These fields help us understand AI-assisted workflows and improve the agent skills. They are only set when the CLI is invoked with agent-specific flags.

## Privacy & security

✅ **Telemetry is optional** — it can be disabled at any time with a single command

✅ **No sensitive data** — credentials, API responses, and business data are never collected

✅ **No data without consent** — you can disable telemetry before running any commands

✅ **Failure-safe** — telemetry errors never affect CLI functionality

✅ **Secure transmission** — all data is sent over HTTPS to a third-party analytics provider

✅ **User control** — debug data is stored locally in user-accessible files

## Common issues

| Issue                   | Solution                                                                   |
| ----------------------- | -------------------------------------------------------------------------- |
| Commands are slow       | Telemetry has a 3-second timeout; network issues won't block your commands |
| Can't disable telemetry | Run `nexudus config set telemetry off`                                     |
| Unsure if disabled      | Run `nexudus config get telemetry`                                         |
| Need to verify disable  | Check `~/.nexudus/config.json` for `"telemetry": "off"`                    |

<Tip>Run `nexudus doctor` at any time to check the CLI's overall health and configuration.</Tip>

## Questions or concerns?

If you have questions about telemetry, want to opt out entirely, or have privacy concerns, please reach out to the Nexudus team or open an issue on the [GitHub repository](https://github.com/Nexudus-Ltd/nexudus-coworking-cli).