> 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

The Revenium CLI tracks Gemini CLI usage by injecting OTLP environment variables into your shell. Once configured, every Gemini CLI session automatically reports telemetry to Revenium.

**Requirements:**

* Gemini CLI installed and configured
* Revenium API key (`hak_` or `rev_` prefix). Get it from Connections > SDK Setup in the Revenium dashboard.
* Node.js >= 20.19.0

## 1. Install the Revenium CLI

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

You can also use `npx` without installing globally:

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

## 2. Run the setup wizard

```bash
revenium-gemini setup
```

The wizard prompts for:

* **Revenium API key** — validated against the `hak_` or `rev_` prefix
* **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` (and `~/.gemini/revenium.fish` for Fish shell) with restricted file permissions (owner read/write only). The wizard also updates your shell profile (bash, zsh, or fish) to source the config automatically.

## 3. Restart your terminal

```bash
# Or reload manually:
source ~/.gemini/revenium.env
```

## 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. Telemetry is captured automatically via the OTLP environment variables injected into your shell. Usage appears in Revenium after the next telemetry flush.

{% hint style="info" %}
**How it works:** The setup wizard writes OTLP environment variables (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_LOGS_EXPORTER`) to a config file and sources it from your shell profile. 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 %}

## Troubleshooting

Start every diagnosis with `revenium-gemini status`. It confirms the configuration exists at `~/.gemini/revenium.env`, reports whether the OTLP environment variables are **loaded in your current shell**, 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 OTLP settings from environment variables that the setup wizard writes to `~/.gemini/revenium.env` and sources from your shell profile. The most common cause of missing data is a shell that was opened before setup, so those variables are not present. Work through these in order:

1. **Check that the environment is loaded.** Run `revenium-gemini status`. Under **Environment**, "Environment variables not loaded in current shell" means Gemini has nothing to export to. The status output prints the exact fix — `source ~/.gemini/revenium.env` (or `~/.gemini/revenium.fish` for the Fish shell).
2. **Reload your shell.** Run `exec $SHELL`, open a new terminal, or `source` the config as above. Gemini reads the OTLP variables **at launch**, so it must be started from a shell where they are present.
3. **Send a synthetic event.** Run `revenium-gemini test --verbose`, then open **AI Assistants > Gemini > Integration Logs** to confirm the event was received. If the test event lands but real usage does not, Gemini is being launched from a shell without the variables loaded — return to step 2.
4. **Run a fresh Gemini session.** Usage appears only for sessions run after the environment is loaded; 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** API key (`hak_` or `rev_` prefix), not a Google or Gemini provider key. A `hak_` key must be in `hak_{tenant}_{key}` form. Get one from **Connections > 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.

## 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     |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.