> 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-codex.md).

# 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 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-codex setup
```

## 2. Run the setup wizard

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

```bash
exec $SHELL
```

## 4. Verify the configuration

```bash
revenium-codex status
```

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

You can also point to a custom config path:

```bash
revenium-codex status --config-path /path/to/config.toml
```

## 5. Send a test metric

```bash
revenium-codex test --verbose
```

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:

```bash
revenium-codex test --verbose --config-path /path/to/config.toml
```

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

```bash
# Backfill from a specific date:
revenium-codex backfill --since 2025-01-01 --to 2025-06-01

# Preview without sending:
revenium-codex backfill --since 2025-01-01 --to 2025-06-01 --dry-run

# Control batch size:
revenium-codex backfill --since 2025-01-01 --batch-size 50

# Custom sessions path:
revenium-codex backfill --sessions-path /path/to/sessions

# Custom config path:
revenium-codex backfill --config-path /path/to/config.toml

# Verbose output:
revenium-codex backfill --since 2025-01-01 -v
```

Backfill is idempotent — deterministic transaction IDs prevent duplicate records.

{% hint style="info" %}
**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.
{% endhint %}

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

```bash
revenium-codex setup --force
```

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

```bash
revenium-codex setup --force
```

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

```bash
revenium-codex status --config-path /path/to/config.toml
```

### 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 **Connections > SDK Setup** 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                  |


---

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