> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/setup-gemini.md).

# Setup Gemini CLI

Revenium reports Gemini CLI spend per developer on the Gemini dashboard under **Usage by User**. To attribute usage to the right person, enter each developer's email in the setup wizard on their machine.

The Revenium CLI tracks Gemini CLI usage by starting each Gemini CLI session with telemetry settings that point at Revenium. Once configured, every Gemini CLI session you start from your terminal reports telemetry to Revenium.

**Requirements:**

* Gemini CLI installed and configured
* Your Revenium metering key (`rev_mk_`). Get it from Integrations > SDK Setup in the Revenium dashboard. The wizard also accepts `rev_sk_` and legacy `hak_` keys, but warns on `rev_sk_`, and it refuses read-only `rev_rk_` keys.
* Node.js >= 20.19.0

## 1. Install the Revenium CLI

Install [`@revenium/cli`](https://www.npmjs.com/package/@revenium/cli) from npm:

```bash
npm install -g @revenium/cli
```

You can also use `npx` without installing globally:

```bash
npx --package @revenium/cli revenium-gemini setup
```

## 2. Run the setup wizard

```bash
revenium-gemini setup
```

The wizard prompts for:

* **Revenium metering key (`rev_mk_`)** — also accepts `rev_sk_` (with a warning) and legacy `hak_` keys; read-only `rev_rk_` keys are refused
* **Email** (optional) — for attribution
* **Organization name** (optional) — for grouping usage
* **Product name** (optional) — for sub-segmenting within the organization
* **API endpoint** (optional) — defaults to `https://api.revenium.ai`

The wizard tests connectivity to the Revenium endpoint before writing the configuration.

Configuration is saved to `~/.gemini/revenium.env` with restricted file permissions (owner read/write only). The wizard also adds a `gemini` wrapper to your shell profile (bash, zsh, or fish). The wrapper starts Gemini CLI through `revenium-gemini run`, which passes the Revenium settings to the Gemini process only, not to your shell. To leave your shell profile unchanged, run setup with `--skip-shell-update` and start Gemini CLI with `revenium-gemini run -- <arguments>`.

## 3. Restart your terminal

If you set up Gemini CLI with a Revenium CLI version earlier than 2.0.0, run `revenium-gemini setup` again so that the `gemini` wrapper is installed.

Open a new terminal, or reload your shell, so that the `gemini` wrapper is active:

```bash
exec $SHELL
```

{% hint style="info" %}
**Scripts, CI jobs and editor integrations:** the wrapper is a shell function, so it applies only to interactive shells. Scripts, Makefiles, CI jobs, editor integrations and `command gemini` start the real binary, and that usage is not sent to Revenium. In those places, run `revenium-gemini run -- <arguments>` instead of `gemini <arguments>`.
{% endhint %}

## 4. Verify the configuration

```bash
revenium-gemini status
```

Confirms that the Revenium endpoint is reachable with the provided credentials.

## 5. Send a test metric

```bash
revenium-gemini test --verbose
```

Sends a zero-cost synthetic event to verify the Revenium pipeline is processing Gemini data. Check AI Assistants > Gemini > Integration Logs to confirm receipt.

## 6. Start using Gemini CLI

After setup, use Gemini CLI as you normally would. The `gemini` wrapper starts each session with the telemetry settings for that process. Usage appears in Revenium after the next telemetry flush.

{% hint style="info" %}
**How it works:** The setup wizard saves your Revenium settings to `~/.gemini/revenium.env`. `revenium-gemini run` reads that file and sets Gemini CLI's telemetry variables, including the `OTEL_EXPORTER_OTLP_HEADERS` header that carries your key, for the Gemini process it starts. Gemini CLI reads these natively and reports usage to Revenium without any additional configuration or sync process.
{% endhint %}

{% hint style="info" %}
**No sync or backfill.** Unlike Copilot and Cursor, Gemini CLI operates in real-time only. Telemetry is exported as each request completes. There is no sync command or backfill capability.
{% endhint %}

## On the dashboard

Open **Intelligence > AI Assistants > Gemini** to see Gemini CLI usage and costs after telemetry begins arriving.

## Troubleshooting

Start every diagnosis with `revenium-gemini status`. It confirms the configuration exists at `~/.gemini/revenium.env`, reports whether the `gemini` wrapper is **installed in your shell profile**, and tests connectivity to the Revenium endpoint.

Because Gemini CLI is real-time only — telemetry is exported as each request completes, with no sync or backfill — the only recourse for missing data is to fix the configuration and run a fresh session. There is no way to recover usage from before metering was working.

### No data appears in Revenium after setup

Gemini CLI reads its telemetry settings from environment variables that `revenium-gemini run` sets from `~/.gemini/revenium.env`. The most common causes of missing data are a terminal that was opened before setup, so the `gemini` wrapper is not active, and a script or tool that starts the real `gemini` binary. Work through these in order:

1. **Check that the wrapper is installed.** Run `revenium-gemini status`. Under **Environment**, "Gemini wrapper is not installed in the shell profile" means plain `gemini` starts without the Revenium settings. Run `revenium-gemini setup` again.
2. **Reload your shell.** Run `exec $SHELL` or open a new terminal. Gemini reads its telemetry settings **at launch**, so start it through the `gemini` wrapper or through `revenium-gemini run`.
3. **Send a synthetic event.** Run `revenium-gemini test --verbose`, then open **Intelligence > AI Assistants > Gemini** and select **View integration logs** to confirm the event was received. If the test event lands but real usage does not, Gemini is being started without the wrapper. Return to step 2, or use `revenium-gemini run -- <arguments>` in scripts and CI jobs.
4. **Run a fresh Gemini session.** Usage appears only for sessions started through the wrapper or `revenium-gemini run`; there is no backfill for earlier activity.

### `status` reports the endpoint is unhealthy, or authentication is rejected

The Revenium endpoint is rejecting the request:

* **Verify the key type.** Gemini telemetry authenticates with a **Revenium** metering key (`rev_mk_`; `rev_sk_` and legacy `hak_` keys also work), not a Google or Gemini provider key. A `hak_` key must be in `hak_{tenant}_{key}` form. Get one from **Integrations > SDK Setup** in the Revenium dashboard.
* **Verify the endpoint.** The default is `https://api.revenium.ai`.
* **Re-enter credentials.** Run `revenium-gemini setup` to rewrite the configuration with a corrected key or endpoint.

If `status` reports a connection failure rather than an auth rejection, confirm your data can actually reach Revenium with a one-line self-test from any terminal — substitute your Revenium key:

```bash
curl -sS -o /dev/null -w "%{http_code}\n" \
  -X POST "https://api.revenium.ai/meter/v2/otlp/v1/logs" \
  -H "x-api-key: rev_mk_your_tenant_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"resourceLogs":[]}'
```

* **`200` / `202`** — your endpoint and key are reaching Revenium correctly.
* **`401` / `403` with an auth message** — the key is wrong, inactive, or not a Revenium key.
* **`403` with no auth body, or a connection failure** — the request is being stopped before it reaches Revenium (for example a corporate network or proxy). [Contact Revenium support](https://www.revenium.io/contact) with your egress IP range so we can confirm connectivity.

If `status` or `test` fails and the only error is `fetch failed`, follow [Corporate networks: proxy or TLS inspection](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/setup-codex.md#corporate-networks-proxy-or-tls-inspection). The same steps apply to `revenium-gemini`.

## Command reference

| Command                              | Description                                                                                    |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `revenium-gemini setup`              | Interactive setup wizard                                                                       |
| `revenium-gemini status`             | Verify connectivity to Revenium                                                                |
| `revenium-gemini test --verbose`     | Send a synthetic test event                                                                    |
| `revenium-gemini run -- <arguments>` | Start Gemini CLI with the Revenium settings for that process (the `gemini` wrapper calls this) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/setup-gemini.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
