How to Check Codex Usage in the CLI
To check Codex usage from the CLI, type /status inside an active Codex terminal session and press Enter. Codex displays the current usage allowances and reset times that apply to your signed-in account. You can verify your remaining capacity immediately from the command line without opening a browser or logging into web settings.
How Do You Run the /status Command in the Codex CLI?
You run /status by entering the slash command inside an active, interactive Codex CLI session prompt. It is an in-session control rather than a standalone shell command. If you run /status from your system shell like Bash or Zsh, your terminal will not recognize it.
To check your usage, start or resume an interactive Codex session first, then issue /status at the session prompt:
OpenAI documents /status as the command for checking account usage and reset times inside the CLI. Typing /usage instead will not display your quota, because slash commands inside the interactive session map to specific internal controls.
What Usage Information Does the Native CLI /status Output Display?
For Plus and Pro accounts where both limits apply, /status can show the 5-hour usage window and weekly allowance along with their reset information. The specific windows displayed depend on your signed-in account tier and plan rules.
Depending on your subscription tier, the output communicates distinct replenishment cycles:
- 5-Hour Usage Window: Tracks near-term prompt activity. OpenAI describes a five-hour usage window where a new window begins when you send the first message after the previous one ends. If this window reaches capacity, subsequent prompt submissions pause until the window expires. ChatGPT Business Premium seats explicitly do not have a 5-hour limit.
- Weekly Allowance: Tracks your broader subscription allocation. This allowance refills according to your account's active reset schedule. Using a purchased or banked reset can change when your weekly allowance resets.
- Reset Information: Displays upcoming reset timing for each active limit so you know when paused prompt submissions will resume.
- In-Flight Turn Behavior: If you reach an account limit during an active turn, OpenAI states that Codex can finish working on that turn subject to fair-use limits before pausing new submissions.
What Is the Difference Between Account Allowance and Context-Window Memory?
The percentage shown by /status represents your account-level subscription allowance, whereas the percentage in the terminal statusline reflects your active conversation's context window. They measure entirely different constraints: context memory tracks immediate conversation capacity, while account allowance meters your plan-wide Codex usage.
Understanding this distinction prevents mistaking a full conversation buffer for an exhausted account:
- Context-Window Remaining (Statusline): Located in the terminal footer, this measures the remaining token space in the active model's context window. As your conversation grows, this number drops. When it nears capacity, Codex triggers auto-compaction (or you can run
/compact) to summarize prior conversation history so the session can continue. - Account Allowance Remaining (/status): Checked through
/statusor web settings, this tracks your consumption against your subscription limits across 5-hour or weekly cycles. - Usage Impact: Triggering compaction does not itself mean your account allowance has been exhausted. However, larger context windows do affect overall token usage on subsequent turns, because OpenAI notes that Codex usage depends in part on context length.
For detailed compaction triggers, buffer thresholds, and model context limits, see our Codex context window guide.
What Usage Details Are Missing from the Native CLI?
OpenAI's documented Codex CLI usage surfaces provide a point-in-time allowance view rather than historical consumption trends, per-prompt subscription token logs, or burn-rate estimates. If you want to track how your allowance changes during a coding session, you otherwise have to keep checking /status.
The native CLI leaves three operational blind spots:
- No Turn-by-Turn Token Breakdown: OpenAI's documented Plus, Pro, and Business subscription surfaces show overall allowance status rather than itemized token receipts for individual prompt turns.
- No Native Pace or Runway Estimates: The native output tells you what remains right now, but it does not calculate your consumption rate per hour or estimate whether you will hit quota before your reset.
- Manual Repeated Checks: Staying aware of your limits requires interrupting your workflow to run
/statusmanually throughout your session.
When Is a Local Monitor More Convenient Than Running /status?
Running /status manually works well for occasional checks, but it interrupts development during heavy coding sessions. If you want continuous visibility without repeatedly typing commands, you can use the local Codex Usage companion to inspect limits or run a lightweight browser dashboard with automatic 60-second refreshes.
The local companion provides two straightforward options:
- One-Shot Shell Command (
codex-usage): Runcodex-usagedirectly from your standard Bash or Zsh prompt to inspect your current allowances and relative reset countdowns without entering an interactive Codex session. - Local Browser Dashboard (
codex-usage --web): Launches a lightweight localhost dashboard that polls your local Codex client every 60 seconds. It tracks observed session pace in memory to show whether your current coding pace will survive until the next reset.
The companion queries your existing authenticated local Codex client. It does not send credentials or usage data to codexusage.dev, and its session pace tracking lives entirely in process memory.
To download the tool or configure the terminal binary, visit the Codex Usage install page.
Frequently Asked Questions About Checking Codex Usage in the CLI
Can I check Codex usage from Bash or Zsh without starting an interactive session?
The native Codex CLI is designed around interactive sessions where /status is entered at the session prompt. If you prefer a non-interactive shell command, running the local companion codex-usage directly from your terminal prints your current allowances and reset countdowns without opening an interactive session first.
Why does the percentage in my statusline differ from /status?
Your terminal statusline displays your active conversation buffer within the model's context window. The /status command reports your account's subscription allowance. Triggering context compaction clears space in your context window, but it does not mean your account subscription quota has run out.
Does the Codex CLI show token counts for individual prompts?
OpenAI’s documented Plus, Pro, and Business subscription surfaces do not provide itemized per-turn token counts in the CLI. For exact per-request API token usage, use an API key and Platform telemetry.