codexbar usage

Synopsis

codexbar [usage] [OPTIONS]
codexbar --provider <id> [OPTIONS]
codexbar --format json [OPTIONS]

The usage command (default) fetches current usage data, credits, and account information from AI providers like Codex and Claude. It mirrors the menubar app’s data paths and supports multiple data sources including web, CLI, OAuth, and API.

Parameters

--provider

string

default:"enabled providers in config"

Provider ID to query. Options:

Specific provider ID (e.g., codex, claude, copilot, gemini, kilo, kimi, minimax, warp, openrouter, synthetic, z.ai)
both - Query default providers (Codex + Claude)
all - Query all enabled providers from config

Provider IDs are defined in ~/.codexbar/config.json.

--format

string

default:"text"

Output format. Options:

text - Human-readable output with progress bars and ANSI colors
json - Machine-readable JSON output

--source

string

default:"auto"

Data source strategy. Options:

auto - (macOS only) Uses browser cookies for Codex + Claude, with CLI fallback when cookies are missing
web - (macOS only) Web-only; no CLI fallback
cli - CLI-only (Codex RPC → PTY fallback; Claude PTY)
oauth - Claude OAuth only (debug); not supported for Codex
api - API key flow when the provider supports it (z.ai, Gemini, Copilot, Kilo, Kimi K2, MiniMax, Warp, OpenRouter, Synthetic)

Linux: web and auto are not supported; CLI exits with error.Output source field reflects the actual strategy used: openai-web, web, oauth, api, local, or provider CLI label.

--account

string

Select a specific token account by label or email. Requires a single --provider.Token accounts are configured in ~/.codexbar/config.json. For Claude, accounts accept either sessionKey cookies or OAuth access tokens (sk-ant-oat...). OAuth requires the user:profile scope.

--account-index

integer

Select token account by 1-based index. Requires a single --provider.

--all-accounts

boolean

Fetch data for all configured accounts for the specified provider. Requires a single --provider.

--no-credits

boolean

Hide Codex credits in text output.

--pretty

boolean

Pretty-print JSON output with indentation.

--status

boolean

Fetch provider status pages and include them in output. Queries status.openai.com, status.anthropic.com, etc.

--antigravity-plan-debug

boolean

Debug flag: print Antigravity planInfo fields to stderr.

--web-timeout

integer

default:"60"

Timeout in seconds for web data source requests.

--web-debug-dump-html

boolean

Write HTML snapshots to /tmp when web scraping fails to extract data.

--no-color

boolean

Disable ANSI colors in text output. Also honors NO_COLOR environment variable or TERM=dumb.

--json-output

boolean

Emit machine-readable JSONL logs on stderr.

--json-only

boolean

Suppress non-JSON output; errors become JSON payloads.

-v, --verbose

boolean

Enable verbose logging.

--log-level

string

Set log level: trace, verbose, debug, info, warning, error, or critical.

-h, --help

boolean

Show help message.

-V, --version

boolean

Show version information.

Response Fields

JSON Output Structure

provider

string

required

Provider ID (e.g., codex, claude, copilot).

account

string

Account identifier when using multi-account tokens.

version

string

Provider CLI or API version (e.g., 0.6.0, 2.0.58).

source

string

required

Actual data source used: openai-web, web, oauth, api, local, or provider-specific CLI label (e.g., codex-cli).

status

object

Provider status page information (when --status is used).

Show status fields

indicator

string

Status indicator: none (operational), minor, major, critical, maintenance, or unknown.

description

string

Status description text.

updatedAt

string

ISO 8601 timestamp of last status update.

url

string

Status page URL.

usage

object

Usage limits and reset times.

Show usage fields

primary

object

Primary usage window (e.g., session limit).

usedPercent

integer

Percentage used (0-100).

windowMinutes

integer

Window duration in minutes (e.g., 300 for 5 hours).

resetsAt

string

ISO 8601 timestamp when usage resets.

secondary

object

Secondary usage window (e.g., weekly limit). Same structure as primary.

tertiary

object

Tertiary usage window (e.g., Sonnet tier). Same structure as primary.

updatedAt

string

ISO 8601 timestamp of when usage was fetched.

identity

object

Account identity information.

providerID

string

Provider identifier.

accountEmail

string

Account email address.

accountOrganization

string

Organization name (if applicable).

credits

object

Credits information (Codex, Kilo, etc.).

Show credits fields

remaining

number

Credits remaining.

updatedAt

string

ISO 8601 timestamp of when credits were fetched.

antigravityPlanInfo

object

Antigravity plan information (when available).

openaiDashboard

object

OpenAI dashboard snapshot with usage breakdown.

Show openaiDashboard fields

signedInEmail

string

Signed-in email address.

codeReviewRemainingPercent

integer

Code review capacity remaining (0-100).

creditEvents

array

Array of credit usage events.

string

Event UUID.

date

string

ISO 8601 timestamp.

service

string

Service name (e.g., CLI, Code Review).

creditsUsed

number

Credits consumed.

dailyBreakdown

array

Daily usage breakdown.

day

string

Date in YYYY-MM-DD format.

services

array

Array of service usage for the day.

totalCreditsUsed

number

Total credits used on that day.

updatedAt

string

ISO 8601 timestamp of dashboard snapshot.

error

object

Error information when provider query fails.

Show error fields

message

string

Error message.

code

string

Error code.

Examples

Default usage (text format)

codexbar

Output:

== Codex 0.6.0 (codex-cli) ==
Session: 72% left [========----]
Resets today at 2:15 PM
Weekly: 41% left [====--------]
Pace: 6% in reserve | Expected 47% used | Lasts until reset
Resets Fri at 9:00 AM
Credits: 112.4 left

== Claude Code 2.0.58 (web) ==
Session: 88% left [==========--]
Resets tomorrow at 1:00 AM
Weekly: 63% left [=======-----]
Pace: On pace | Expected 37% used | Runs out in 4d
Resets Sat at 6:00 AM
Sonnet: 95% left [===========-]
Account: [email protected]
Plan: Pro

Query specific provider with JSON output

codexbar --provider claude --format json --pretty

Output:

{
  "provider": "codex",
  "version": "0.6.0",
  "source": "openai-web",
  "status": {
    "indicator": "none",
    "description": "Operational",
    "updatedAt": "2025-12-04T17:55:00Z",
    "url": "https://status.openai.com/"
  },
  "usage": {
    "primary": {
      "usedPercent": 28,
      "windowMinutes": 300,
      "resetsAt": "2025-12-04T19:15:00Z"
    },
    "secondary": {
      "usedPercent": 59,
      "windowMinutes": 10080,
      "resetsAt": "2025-12-05T17:00:00Z"
    },
    "tertiary": null,
    "updatedAt": "2025-12-04T18:10:22Z",
    "identity": {
      "providerID": "codex",
      "accountEmail": "[email protected]",
      "accountOrganization": null,
      "loginMethod": "plus"
    }
  },
  "credits": {
    "remaining": 112.4,
    "updatedAt": "2025-12-04T18:10:21Z"
  },
  "openaiDashboard": {
    "signedInEmail": "[email protected]",
    "codeReviewRemainingPercent": 100,
    "creditEvents": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "date": "2025-12-04T00:00:00Z",
        "service": "CLI",
        "creditsUsed": 123.45
      }
    ],
    "dailyBreakdown": [
      {
        "day": "2025-12-04",
        "services": [
          {
            "service": "CLI",
            "creditsUsed": 123.45
          }
        ],
        "totalCreditsUsed": 123.45
      }
    ],
    "updatedAt": "2025-12-04T18:10:21Z"
  }
}

Query all providers

codexbar --provider all --format json --pretty

Query with status page data

codexbar --status

Query specific account

codexbar --provider claude --account [email protected]
codexbar --provider claude --account-index 2

Query all accounts for a provider

codexbar --provider claude --all-accounts --format json --pretty

Use API key source

COPILOT_API_TOKEN=ghp_xxx codexbar --provider copilot --format json --pretty
KILO_API_KEY=sk_xxx codexbar --provider kilo --source api --format json --pretty
codexbar --provider gemini --source api --format json --pretty

Machine-readable output only

codexbar --json-only --format json --pretty

Use web source explicitly

codexbar --provider codex --source web --format json --pretty

Exit Codes

0: Success
1: Unexpected failure
2: Provider binary not found (not on PATH)
3: Parse/format error
4: CLI timeout

Notes

Configuration

CLI reads ~/.codexbar/config.json for provider settings, secrets, and ordering
Enabled providers and their order are respected from config
Reset times follow the in-app reset time display setting (default: countdown)

Web Data Sources

Codex web: OpenAI web dashboard (usage limits, credits, code review, usage breakdown)
- Requires signed-in session in Safari, Chrome, or Firefox at chatgpt.com
- No passwords stored; CodexBar reuses browser cookies
- Safari may require Full Disk Access (System Settings → Privacy & Security → Full Disk Access)
- openaiDashboard JSON field is normally cached; --source auto|web refreshes live via WebKit
Claude web: claude.ai API (session + weekly usage, plus account metadata)
- Uses browser cookies or OAuth tokens from config

Text Output

Uses ANSI colors when stdout is a rich TTY
Disable colors with --no-color, NO_COLOR environment variable, or TERM=dumb
Progress bars show usage percentage visually
Reset lines show countdown or absolute time based on app preferences

API Keys

Copilot: Requires apiKey in config or COPILOT_API_TOKEN environment variable
Kilo: Supports KILO_API_KEY environment variable
Gemini, z.ai, etc.: Configure API keys in ~/.codexbar/config.json

Data Source Priority

Codex: Prefers RPC, falls back to PTY
Claude: Defaults to web with CLI fallback when cookies are missing
Kilo auto: app.kilo.ai API first, then CLI auth fallback (~/.local/share/kilo/auth.json)

CLI Commands

Provider API

Synopsis

Parameters

Response Fields

JSON Output Structure

Examples

Default usage (text format)

Query specific provider with JSON output

Query all providers

Query with status page data

Query specific account

Query all accounts for a provider

Use API key source

Machine-readable output only

Use web source explicitly

Exit Codes

Notes

Configuration

Web Data Sources

Text Output

API Keys

Data Source Priority

Build docs developers (and LLMs) love

CLI Commands

Provider API

​Synopsis

​Parameters

​Response Fields

​JSON Output Structure

​Examples

​Default usage (text format)

​Query specific provider with JSON output

​Query all providers

​Query with status page data

​Query specific account

​Query all accounts for a provider

​Use API key source

​Machine-readable output only

​Use web source explicitly

​Exit Codes

​Notes

​Configuration

​Web Data Sources

​Text Output

​API Keys

​Data Source Priority

Build docs developers (and LLMs) love

Synopsis

Parameters

Response Fields

JSON Output Structure

Examples

Default usage (text format)

Query specific provider with JSON output

Query all providers

Query with status page data

Query specific account

Query all accounts for a provider

Use API key source

Machine-readable output only

Use web source explicitly

Exit Codes

Notes

Configuration

Web Data Sources

Text Output

API Keys

Data Source Priority