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

# analytics

> Pin the Plausible Community Edition version that the analytics role runs, and store the Stats API key the Gateway uses to read visits.

The `analytics` role runs Plausible Community Edition for the fleet as one Docker Process named `plausible`. The `analytics` family changes the version that Process runs and stores the Stats API key the Gateway uses to read visits. [`node:role:add`](/docs/cli/node#orbit-noderoleadd) assigns the role and [`node:role:remove`](/docs/cli/node#orbit-noderoleremove) removes it.

The [Analytics role](/docs/reference/analytics) reference owns the storage Processes, the private dashboard, and what removal keeps. [Instance analytics stats](/docs/reference/instance-analytics-stats) owns the read that uses the stored key.

## Commands

| Command | Result |
| - | - |
| [`analytics:update`](#orbit-analyticsupdate) | Pin another Plausible version and replace the `plausible` Process. |
| [`analytics:credentials`](#orbit-analyticscredentials) | Show whether a Stats API key is stored, store one, or clear it. |

Every command accepts `--json`. The caller must be the Gateway Node or hold an access grant to it.

## orbit analytics:update

Pin another Plausible Community Edition version for the analytics role.

```bash theme={"dark"}
orbit analytics:update [version] [--json]
```

| Argument | Required | Meaning |
| - | - | - |
| `version` | when the command cannot prompt | The version as three numbers, for example `3.2.1`. The Gateway runs the image tag `v` plus that version. |

```bash theme={"dark"}
orbit analytics:update 3.2.1
orbit analytics:update 3.2.1 --json
```

In a terminal the command asks for the version you left out. With `--json` or `--no-interaction` it refuses a missing version.

The Gateway stores the version and converges the role again, which replaces the `plausible` Process. Plausible keeps no data in its container, and it migrates its PostgreSQL database each time it starts, so the replaced Process continues with the same data. When the new version does not converge, the Gateway stores the earlier version again and returns the error. It does not converge the earlier version again, so the `plausible` Process can stay failed. Converge the role again with `orbit node:role:add NODE analytics --converge --postgres-process=ID --clickhouse-process=ID` to restore it. Naming the version that already runs changes nothing.

Human output names the Node, the version, and the previous version. JSON returns `node_id`, `node_name`, `version`, `previous_version`, and the request ID.

| Error code | Meaning |
| - | - |
| `analytics.version_invalid` | The version is missing or is not three numbers. The CLI refuses it before any request. |
| `validation.failed` | The Gateway refused the version. |
| `analytics.role_missing` | No Node has an active analytics role. |

## orbit analytics:credentials

Show whether the Gateway has a Plausible Stats API key, store one, or clear it.

```bash theme={"dark"}
orbit analytics:credentials [--set] [--api-key=KEY] [--unset] [--json]
```

| Option | Meaning |
| - | - |
| `--set` | Store a key. In a terminal the command asks for it when `--api-key` is absent. |
| `--api-key` | The key to store. Use it with `--set`. |
| `--unset` | Clear the stored key. |

```bash theme={"dark"}
orbit analytics:credentials
orbit analytics:credentials --set
orbit analytics:credentials --set --api-key=plausible-read-only-key
orbit analytics:credentials --unset --json
```

The command never prints the key. Human output says whether a key is stored and names the driver `plausible_ce`. JSON returns `configured`, `driver`, and the request ID.

Create the key in Plausible at `https://analytics.orbit`, then store it here. The Gateway sends it only to the fleet Plausible Stats API. `--set` and `--unset` together are refused.

| Error code | Meaning |
| - | - |
| `analytics.credentials_conflict` | `--set` and `--unset` were both given. |
| `analytics.api_key_invalid` | The key is missing, shorter than 8 or longer than 512 characters, or holds control characters. The CLI refuses it before any request. |

The Gateway stores the key even while no analytics role is assigned. The next stats read uses it.

## Related

* [`node`](/docs/cli/node) assigns and removes the analytics role.
* [`process`](/docs/cli/process) reads the logs of the `plausible` Process and restarts it.
* [`instance:analytics`](/docs/cli/instance) publishes a tracking host.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.