cli-reference.md

CLI Reference

This page lists the common command-line workflows. For tested JSON contract ids, payload shapes, and error codes, see CLI And MCP JSON Schemas.

Index And Setup

Run first-time setup:

codex-usage-tracker setup

setup installs or refreshes the local plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs doctor, and prints whether Codex needs a restart for plugin discovery.

Refresh the local aggregate index:

codex-usage-tracker refresh

Rebuild the local aggregate index after parser or schema changes:

codex-usage-tracker rebuild-index

rebuild-index clears only the local aggregate usage_events and refresh metadata tables, then rescans local Codex logs.

Inspect one Codex log without writing to SQLite:

codex-usage-tracker inspect-log ~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl
codex-usage-tracker inspect-log ~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl --json

inspect-log reports parser adapter, aggregate token-count events, session ids, models, and parser diagnostics. It does not store raw prompts, assistant messages, tool output, or transcript snippets.

Check setup without writing files:

codex-usage-tracker doctor
codex-usage-tracker doctor --suggest-repair

doctor validates local paths, database state, parser diagnostics, pricing and allowance config, dashboard output, plugin files, and MCP importability. --suggest-repair adds likely next commands without making changes.

Reset only the local aggregate database:

codex-usage-tracker reset-db --yes

reset-db deletes tracker-owned aggregate SQLite rows. It does not delete raw Codex logs and requires --yes.

Plugin Lifecycle

codex-usage-tracker install-plugin
codex-usage-tracker install-plugin --python .venv/bin/python
codex-usage-tracker upgrade-plugin
codex-usage-tracker uninstall-plugin

install-plugin writes the package-owned local Codex plugin wrapper, companion skills, and MCP config. Use the --python form for source checkouts that should use a repo-local virtual environment.

upgrade-plugin refreshes an existing wrapper in place. uninstall-plugin removes only the tracker-owned plugin wrapper and marketplace entry.

Dashboard

codex-usage-tracker dashboard --open
codex-usage-tracker dashboard --include-archived --open
codex-usage-tracker open-dashboard
codex-usage-tracker open-dashboard --no-refresh
codex-usage-tracker serve-dashboard --open
codex-usage-tracker serve-dashboard --no-refresh --open
codex-usage-tracker serve-dashboard --no-context-api --open

serve-dashboard --context-api explicit is the default and keeps context loading as an explicit per-row action. serve-dashboard --no-context-api or --context-api disabled starts with context loading off; a token-protected button in the local details panel can enable it without restarting the server.

open-dashboard and serve-dashboard refresh active-session logs before opening by default. Use --no-refresh only for an intentionally cached snapshot. The lower-level dashboard command writes from the current SQLite index and does not rescan logs.

Dashboards default to active sessions only. Use --include-archived for an all-history static/opened dashboard, or switch the served dashboard's History control from Active sessions only to All history when you intentionally want archived logs scanned and included.

Use global --lang <code> before the dashboard command, or set CODEX_USAGE_TRACKER_LANG, to choose the dashboard's initial UI language. The dashboard language selector can then override that default in the browser. Localization applies to dashboard UI text, not JSON fields, CSV columns, model names, thread names, paths, or full CLI output.

The localhost /api/usage endpoint accepts limit and offset query parameters, so automation can page aggregate rows without asking the server to load an entire large history at once.

Summaries

codex-usage-tracker summary --group-by model
codex-usage-tracker summary --group-by project
codex-usage-tracker summary --group-by project_tag
codex-usage-tracker summary --group-by thread --limit 20
codex-usage-tracker summary --preset today
codex-usage-tracker summary --preset last-7-days
codex-usage-tracker summary --preset expensive
codex-usage-tracker summary --preset by-subagent-role
codex-usage-tracker expensive --limit 10
codex-usage-tracker recommendations --limit 10
codex-usage-tracker pricing-coverage

Useful investigations:

• Sort by Highest Codex credits to find calls or threads consuming the most usage allowance.
• Sort by Cache to find threads that are mostly new context versus mostly reused context.
• Sort by Context to find calls approaching the model context window.
• Filter by model or reasoning effort to compare usage patterns across model choices.
• Use summary --preset by-subagent-role to see whether delegated work is driving a large share of usage.
• Use expensive --limit 10 for a quick list of the highest-cost calls.
• Use recommendations --json for ranked action rows and thread rollups with severity score, primary recommendation, and secondary signals.

JSON Queries

codex-usage-tracker query --since 2026-06-01 --project codex-usage-tracker --min-credits 1
codex-usage-tracker query --pricing-status unpriced --limit 0
codex-usage-tracker recommendations --since 2026-06-01 --json
codex-usage-tracker summary --group-by model --json
codex-usage-tracker session <session-id> --json

Use query when you need stable JSON for automation across project, model, effort, thread, pricing, token, or credit filters.

Session And Context

Show one session:

codex-usage-tracker session <session-id>

Load one call's logged context on demand:

codex-usage-tracker context <record-id>
codex-usage-tracker context <record-id> --max-entries 0 --max-chars 0
codex-usage-tracker context <record-id> --include-tool-output
codex-usage-tracker context <record-id> --include-compaction-history

Raw context is read from the original local JSONL source only when explicitly requested. It is not written to SQLite, CSV, or generated dashboard HTML. The default response is bounded; use --max-entries 0 to request all matching context entries and --max-chars 0 to remove the character cap for that explicit request. Tool output and compacted replacement history are omitted unless explicitly requested with their flags, and returned text is still redacted.

Export

codex-usage-tracker export --output usage.csv
codex-usage-tracker export --output usage.csv --limit 0

Use --privacy-mode redacted or --privacy-mode strict before sharing CSV output.

Support Bundle

codex-usage-tracker --privacy-mode strict support-bundle --output ~/.codex-usage-tracker/support-bundle.json

Support bundles are diagnostic summaries for issues. They include package, platform, doctor, schema, parser, pricing, allowance, threshold, project-config, and privacy metadata. They exclude raw logs, aggregate rows, prompts, assistant messages, tool output, and context text.

Local Config

codex-usage-tracker update-pricing
codex-usage-tracker pin-pricing --output ~/.codex-usage-tracker/pricing-2026-06-05.json
codex-usage-tracker init-pricing
codex-usage-tracker update-rate-card
codex-usage-tracker init-allowance
codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"
codex-usage-tracker init-thresholds
codex-usage-tracker init-projects

Local config files live under ~/.codex-usage-tracker/ and are never committed by this project.

Stable local config files:

• pricing.json: schema _schema: codex-usage-tracker-pricing-v1, optional _source, models, aliases, and _estimated_models. models maps model labels to USD-per-million-token rates such as input, cached_input, and output.
• rate-card.json: schema codex-usage-tracker-codex-rate-card-v1, optional _source, credit_rates, and aliases. credit_rates maps Codex model labels to credit rates for aggregate token counters.
• allowance.json: schema codex-usage-tracker-allowance-v1, windows, optional credit_rates, and aliases. windows stores copied 5-hour, weekly, or other allowance snapshots such as remaining_percent, reset_at, remaining_credits, and total_credits.
• thresholds.json: JSON object keyed by recommendation threshold names such as low_cache_ratio, high_context_percent, and high_cost_usd. Unknown keys are ignored.
• projects.json: JSON object with aliases, ignored_paths, and tags for local project attribution.

These config schemas are part of the 1.0 compatibility surface. New optional fields may be added, but existing meanings should not change without documentation and a compatibility plan.

Privacy Mode

--privacy-mode is a global option, so place it before the subcommand:

codex-usage-tracker --privacy-mode redacted dashboard --open
codex-usage-tracker --privacy-mode strict export --output usage-redacted.csv
codex-usage-tracker --privacy-mode strict query --since 2026-06-01

normal keeps local project metadata visible. redacted hides raw cwd and source paths, hides Git remote labels, and replaces unnamed projects with stable hashed labels. strict also hides project-relative cwd, Git branch, and project tags.