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 Settings > API Keys in the Revenium dashboard.

• Node.js >= 20.19.0

1. Install the Revenium CLI

npm install -g @revenium/cli

You can also use npx without installing globally:

npx @revenium/cli revenium-gemini setup

2. Run the setup wizard

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

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

4. Verify the configuration

revenium-gemini status

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

5. Send a test metric

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.

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.

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.

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 Settings > API Keys 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:

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