Ctrlk
API DOCS
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Setup Codex CLI

The Revenium CLI tracks OpenAI Codex CLI usage by writing OTLP configuration to the Codex config.toml and injecting a shell wrapper that sets the correct environment for each session.

Requirements:

  • OpenAI Codex 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-codex setup

2. Run the setup wizard

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

  • Config path (optional) — defaults to ~/.codex/config.toml

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

Configuration is written to the [otel] section of ~/.codex/config.toml. If an existing [otel] section is found, the wizard prompts before overwriting (use --force to skip the prompt).

The wizard also creates a shell wrapper function so that conflicting OTLP environment variables from other tools are automatically unset before Codex runs.

3. Restart your terminal

4. Verify the configuration

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

You can also point to a custom config path:

5. Send a test metric

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

You can also test with a custom config path:

6. Start using Codex CLI

After setup, use Codex CLI as you normally would. The config.toml [otel] section tells Codex where to send telemetry, and the shell wrapper ensures no conflicting environment variables interfere. Usage appears in Revenium after the next telemetry flush.

7. Backfill historical data

To import historical Codex usage from local session logs:

Backfill is idempotent — deterministic transaction IDs prevent duplicate records.

Shell wrapper: The setup creates a shell function that wraps the codex binary. This function unsets OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_PROTOCOL, and OTEL_LOGS_EXPORTER before running Codex, so that environment variables from other tools (like Claude Code or Gemini) do not conflict with Codex's config.toml settings.

8. Troubleshooting

Start every diagnosis with revenium-codex status — it checks, in order, that the config exists, is in the correct form, has telemetry enabled, and can reach Revenium, and it names the exact fix for whatever it finds.

No data appears in Revenium after setup

The most common cause is that the current shell is still running without the wrapper that Codex needs. Work through these in order:

  1. Restart your terminal. Run exec $SHELL or open a new terminal window so the shell wrapper installed during setup is active. Codex reads its telemetry environment through that wrapper.

  2. Check the configuration. Run revenium-codex status. It reports whether the [otel] config is present and valid and whether the Revenium endpoint is reachable.

  3. Send a synthetic event. Run revenium-codex test --verbose, then open AI Assistants > Codex > Integration Logs to confirm the event was received. If the test event lands but real sessions do not, Codex is running outside the wrapper — return to step 1.

  4. Confirm a session has flushed. Usage appears only after Codex's next telemetry flush, so allow a completed Codex session before expecting data.

status reports "legacy flat-key [otel] form"

An older or hand-edited config.toml can store the [otel] settings in a flat form that Codex silently ignores — the configuration looks present but no telemetry is exported. Migrate it to the supported form:

status reports missing [features] runtime_metrics = true

Codex only emits OpenTelemetry data when runtime metrics are enabled. If this flag is absent, no usage is sent even though the [otel] block is otherwise correct. Restore it with:

status reports "No Codex config found"

There is no [otel] configuration at ~/.codex/config.toml. Run revenium-codex setup to create it. If you keep Codex's config in a non-default location, point the CLI at it:

Connection check fails, or authentication is rejected

If status or test reports a failed connection or a rejected key:

  • Verify the key type. Codex telemetry authenticates with a Revenium API key (hak_ or rev_ prefix), not an OpenAI or other provider key. A provider key authenticates model calls; it will not authenticate telemetry ingest. Get a Revenium key from Settings > API Keys in the Revenium dashboard.

  • Verify the endpoint. Confirm it matches your Revenium environment. The default is https://api.revenium.ai.

  • Re-enter credentials. Run revenium-codex setup --force to rewrite the [otel] block with a corrected key or endpoint.

Telemetry conflicts with another AI tool

If Codex data is missing or misattributed on a machine that also runs Claude Code or Gemini, a conflicting OTLP environment variable from the other tool is the likely cause. Always launch Codex through a shell that has loaded the Revenium wrapper (restart your terminal after setup) — the wrapper unsets the conflicting variables before Codex runs.

Command reference

Command
Description

revenium-codex setup

Interactive setup wizard

revenium-codex setup --force

Setup, overwriting existing [otel] section

revenium-codex status

Verify connectivity to Revenium

revenium-codex test --verbose

Send a synthetic test event

revenium-codex backfill --since <date> --to <date>

Import historical session data

revenium-codex backfill --dry-run

Preview backfill output without sending

revenium-codex backfill --batch-size <n>

Control backfill throughput

revenium-codex backfill --sessions-path <path>

Custom sessions directory

revenium-codex backfill --config-path <path>

Custom config.toml location

PreviousSetup Gemini CLINextAI Assistant Data Reference

Last updated

Was this helpful?