codex-ops
codex-ops is a Rust CLI for local Codex auth profiles, session usage, and
weekly cycle workflows.
The public command and Rust crate name are both codex-ops. The npm package is
only a thin distribution shim: it detects the current platform, finds the
prebuilt Rust binary from an optional platform package, and forwards argv,
stdio, signals, and exit codes. It does not expose a JavaScript import API and
does not contain JavaScript business logic.
Usage
After the npm package is published, run it directly with:
After the crate is published, Rust users can install the same CLI with:
Local development in this repository uses Cargo for the product binary:
The npm shim can be tested against the local release binary:
The Rust CLI fixture smoke runs as an integration test:
Published npm installs support Node.js >=20.12.0 for the shim. Local
development requires a Rust stable toolchain; Node.js >=20.12.0 is only
needed for npm shim, packaging, and release helper scripts.
Commands
Auth
Syntax:
Auth commands read auth.json from $CODEX_HOME/auth.json by default, or
~/.codex/auth.json when CODEX_HOME is not set. It expects the fixed Codex
auth structure and decodes tokens.id_token without verifying the signature.
auth status prints only the key account fields: account ID, key ID, name,
email, user ID, plan, and organizations. It never prints the raw ID token.
auth save persists the entire current auth.json under the profile store
using the account ID as the unique key. By default the store is
$CODEX_HOME/codex-ops/auth-profiles; --auth-file only changes which
auth file is read. Use --store-dir to choose a different profile store.
auth list only shows the current profile and readable persisted profiles. If a
persisted profile cannot be decoded, it is listed under skipped profiles instead
of failing the whole command. auth select switches to a persisted profile; in
an interactive terminal it uses an Up/Down/Enter selection list, saves the
current auth.json first, then replaces auth.json with the selected persisted
content. The first switch also initializes
$CODEX_HOME/codex-ops/auth-account-history.json from the current
auth.json, then records each successful auth select timestamp so usage can be
attributed back to the active account. --store-dir only moves saved auth
profiles; use --account-history-file if the account history itself should live
somewhere else. auth remove shows an interactive multi-select list where Space
toggles entries and Enter confirms the selection, then asks for a second
confirmation before deleting persisted copies. The interactive remove list does
not offer the currently active profile, and cancelling an interactive prompt
leaves auth files, saved profiles, and account history unchanged.
Options:
| Option | Behavior |
|---|---|
--auth-file <path> |
Use a specific auth.json file. |
--codex-home <path> |
Read <path>/auth.json. Ignored when --auth-file is supplied. |
--store-dir <path> |
Use a specific auth profile store directory for save, list, select, and remove. |
--account-history-file <path> |
Use a specific auth account history file for select. |
-j, --json |
Print JSON output with the summarized auth fields. |
--include-token-claims |
Include the decoded JWT header and claims in JSON output. |
-A, --account-id <id> |
Select or remove a specific persisted profile. |
-y, --yes |
Skip confirmation when removing with --account-id. |
Stat
Syntax:
stat reads Codex session JSONL files from ~/.codex/sessions by default.
Use --codex-home or --sessions-dir to point it at another Codex data
directory. The default scanner reads rollout files in the requested range and
checks older rollout files in a bounded lookback window by their last
token_count timestamp before deciding whether to read them. The lookback is
min(max((end - start) / 2, 2 days), 7 days).
Use -F, --full-scan when you need exact local token_count results across
long sessions that may have started before the requested range. Full scan checks
all rollout files before the requested range by last token_count timestamp.
Date-ranged non-full-scan table and Markdown output includes a reminder, and
JSON output includes the same message in warnings.
Use --group-by account or --account-id <id> to initialize/read
auth-account-history.json and attribute token_count events by the account
active at each event timestamp.
Views:
| Command | Output |
|---|---|
codex-ops stat |
Aggregate token usage by the resolved group-by value. |
codex-ops stat sessions |
Top sessions by credits by default. |
codex-ops stat sessions <session-id> |
Event-level token usage timeline for one session. |
Weekly Limit Cycles
Syntax:
cycle estimates Codex weekly-limit usage from local token_count events
and user-provided anchors. It does not call Codex or OpenAI services and it does
not implement 5-hour limit windows.
A weekly anchor is the first real use that starts a weekly limit cycle. The cycle resets 168 hours later. If no local usage occurs after that reset, no new cycle is opened yet; the next local usage event after reset becomes the next cycle start.
Anchors are stored by account in
$CODEX_HOME/codex-ops/stat-cycles.json. The account is resolved from
--account-id, then the current auth.json account, then the fallback
default account bucket. Cycle usage reads auth-account-history.json when
available so usage from other accounts is not mixed into the selected account.
Use --cycle-file <path> for an isolated store.
Examples:
cycle add accepts one or more times. Quote values that contain spaces, or
pass common YYYY-MM-DD HH:mm values as unquoted date/time pairs. Time input
with an explicit offset, such as 2026-05-01T08:00:00+08:00, is parsed using
that offset. Time input without an offset, such as 2026-05-01 08:00, is
interpreted in the current system time zone. Stored anchors keep the original
input and save the instant as UTC ISO. Use -n, --note <text> to attach a note
to added anchors.
History reports include a stable cycle ID in each row. Manual cycles use the
anchor ID, derived cycles use cyc_<UTC-start>, and estimated cycles use
est_<UTC-start>. Pass one of those IDs to cycle history <cycle-id> to show
current-style details for that cycle, including by-day and by-model breakdowns.
Use cycle history --select in an interactive terminal to choose from matching
history rows.
Cycle reports mark each row with a source:
| Source | Meaning |
|---|---|
manual |
Cycle start came from a user anchor. |
derived |
Cycle start came from the first local usage event after reset. |
estimated |
Pre-anchor history was included only because --estimate-before-anchor was supplied. |
unanchored |
No usable anchor exists for the selected account. |
By default, history before the earliest anchor is not reported as exact. Use
--estimate-before-anchor only when you want fixed 168-hour pre-anchor buckets
clearly labeled as estimated. current table output shows the current cycle
summary, a by-day breakdown, and a by-model breakdown; JSON output includes the
same data as current, byDay, and byModel. current and history read
session JSONL files from the normal stat sessions directory and enable full
JSONL file scanning so long sessions are filtered by event time instead of
rollout filename time.
Cycle options:
| Option | Behavior |
|---|---|
-A, --account-id <id> |
Use a specific cycle account bucket. |
--cycle-file <path> |
Use a specific anchor store file. |
--auth-file <path> |
Use a specific auth.json when resolving the account. |
--codex-home <path> |
Resolve auth.json, sessions, and the default cycle file under this Codex home. |
--sessions-dir <path> |
Use a specific sessions directory for current and history. |
-i, --select |
Interactively select a history cycle to show in detail. |
--estimate-before-anchor |
Include pre-anchor estimated history rows. |
Time range options:
| Option | Behavior |
|---|---|
-s, --start <time> |
Start time. Date-only values start at local 00:00:00.000. |
-e, --end <time> |
End time. Date-only values end at local 23:59:59.999. |
-t, --today |
Current local day through now. |
--yesterday |
Previous local day. |
-m, --month |
Current local calendar month through now. |
-L, --last <duration> |
Recent duration such as 12h, 7d, 2w, or 1mo. |
-a, --all |
Scan and include all session usage records without date pruning. |
When --group-by is not supplied, stat chooses a default from the resolved
time range: ranges up to 48 hours use hour, ranges up to 31 days use day,
ranges up to six calendar months use week, and longer ranges use month.
--month remains grouped by day by default, while --all defaults to
month.
Aggregation and shaping options:
| Option | Behavior |
|---|---|
-g, --group-by <group> |
Aggregate by hour, day, week, month, model, or cwd. Ignored by sessions views. |
-S, --sort <sort> |
Sort rows by time, tokens, credits, calls, or sessions. |
-n, --limit <n> |
Cap output rows. For sessions <session-id>, this caps displayed events while totals still cover the whole matched session. |
-T, --top <n> |
Session-list row count. When both --top and --limit are supplied to stat sessions, --top wins. |
-d, --detail |
Show full event-level rows for stat sessions <session-id>. |
-F, --full-scan |
Scan all session files instead of pruning by date. |
-r, --reasoning-effort |
When grouping by model, append Codex reasoning effort to the model key. |
-A, --account-id <id> |
Only include usage attributed to an account id. |
When --reasoning-effort is combined with --group-by model, Codex reasoning
effort is appended when present, for example gpt-5.5-high or
gpt-5.5-xhigh. Pricing still uses the base model name.
Output options:
| Option | Behavior |
|---|---|
-f, --format <format> |
Output table, json, csv, or markdown. |
-j, --json |
Alias for --format json. |
-v, --verbose |
Include scan and parsing diagnostics in table output. JSON output always includes diagnostics. |
Diagnostics include scanned/skipped directories, read/skipped files, read lines, invalid JSON lines, token-count events, included usage events, skipped-event reasons, and file read concurrency.
Credits are estimated from the token counters in each session. Cached input
tokens are billed at the cached-input rate; regular input credits use
max(inputTokens - cachedInputTokens, 0). USD estimates use 25 credits = $1.
When a model has no configured price, it is excluded from Credits and listed in
an unpriced-model breakdown with a stub you can fill into
data/codex-rate-card.json.
JSON output includes the same information under unpricedModels.
Pricing data is statically embedded from data/codex-rate-card.json. The
current snapshot source is OpenAI Help Center Codex rate card, checked
2026-05-13.
| Model | Input / 1M | Cached input / 1M | Output / 1M | Note |
|---|---|---|---|---|
| GPT-5.5 | 125 credits | 12.50 credits | 750 credits | |
| GPT-5.4 | 62.50 credits | 6.250 credits | 375 credits | |
| GPT-5.4-mini | 18.75 credits | 1.875 credits | 113 credits | |
| GPT-5.3-Codex | 43.75 credits | 4.375 credits | 350 credits | |
| GPT-5.2 | 43.75 credits | 4.375 credits | 350 credits | |
| GPT-5.3-Codex-Spark | 0 credits | 0 credits | 0 credits | research preview; charged at 0 credits |
| GPT-Image-2 (image) | 200 credits | 50 credits | 750 credits | |
| GPT-Image-2 (text) | 125 credits | 31.25 credits | 250 credits |
Development
The CLI implementation lives in standard Cargo source paths. Keep business logic in Rust; JavaScript is reserved for the npm shim and release helper scripts.
The repository also includes a justfile for local orchestration. Recipes only
compose existing Cargo and npm commands; assertions and fixture behavior belong
in Rust tests or dedicated helper scripts. In this workspace, run recipes
through RTK:
The default benchmark command is Rust-only and uses the synthetic fixture in
test/fixtures/rust-run. Larger 100x benchmark data is local-only and must not
be committed.
Node scripts under scripts/ are reserved for npm shim smoke and npm release
packaging. Default CLI smoke and benchmark coverage should stay in Rust tests
or Rust helper binaries.
Package Layout
src/main.rs Rust CLI process entry
src/lib.rs Rust command parsing and dispatch
src/*.rs Rust business modules
src/bin/codex-ops-bench.rs Local Rust benchmark smoke helper
bin/codex-ops.js npm shim entrypoint
npm/<target>/package.json npm platform package manifests
justfile local command orchestration
scripts/*.mjs npm shim/release helpers
test/fixtures/rust-run/ synthetic fixture data only
The published Cargo crate exposes only the codex-ops binary. Local helper
binaries, npm packaging assets, CI configuration, task documents, and synthetic
fixtures are excluded from the crate package; they remain repository-only
development assets.
Release
GitHub Actions builds release artifacts for:
linux-x64-gnu
linux-arm64-gnu
darwin-x64
darwin-arm64
win32-x64-msvc
Supported Linux npm packages require GNU/glibc. Alpine Linux and other Linux musl targets are not currently supported; the npm shim exits with an explicit unsupported-platform error instead of searching for a missing musl package.
Each artifact contains the Rust binary, manifest.json, and SHA256SUMS. The
main npm package depends on platform packages named codex-ops-<target> through
optionalDependencies. The release workflow validates Cargo/npm version
synchronization and only publishes when manually triggered with the explicit
publish confirmation and configured CARGO_REGISTRY_TOKEN / NPM_TOKEN
secrets.
Before publishing, recheck npm platform package name availability, crates.io
token access, GitHub release environment approval, the first release version,
and whether any legacy migration package or alias is needed.
Data Safety
codex-ops reads local Codex files such as $CODEX_HOME/auth.json,
$CODEX_HOME/sessions, and $CODEX_HOME/codex-ops/*. Do not commit real
auth files, raw session JSONL, account IDs, tokens, cwd values, or user content.
Use only synthetic fixtures under test/fixtures/**.