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_orrev_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/cliYou can also use npx without installing globally:
npx @revenium/cli revenium-codex setup2. Run the setup wizard
revenium-codex setupThe wizard prompts for:
Revenium API key — validated against the
hak_orrev_prefixEmail (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.aiConfig 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:
Restart your terminal. Run
exec $SHELLor open a new terminal window so the shell wrapper installed during setup is active. Codex reads its telemetry environment through that wrapper.Check the configuration. Run
revenium-codex status. It reports whether the[otel]config is present and valid and whether the Revenium endpoint is reachable.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.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"
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
status reports missing [features] runtime_metrics = trueCodex 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"
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_orrev_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 --forceto 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
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
Last updated
Was this helpful?