Skip to main content
A lightweight Commander-based CLI that mirrors the menubar app’s data paths (Codex web/RPC → PTY fallback; Claude web by default with CLI fallback and OAuth debug). Use it when you need usage numbers in scripts, CI, or dashboards without UI.

​
Installation

​
macOS

In the app: Preferences → Advanced → Install CLI. This symlinks CodexBarCLI to /usr/local/bin/codexbar and /opt/homebrew/bin/codexbar.

​
Repository Script

From the repo: 
./bin/install-codexbar-cli.sh
This creates the same symlink targets as the app preference. 
ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar

​
Linux

​
Homebrew (Linuxbrew)

brew install steipete/tap/codexbar

​
Direct Download

Download CodexBarCLI-v<tag>-linux-<arch>.tar.gz from GitHub Releases (x86_64 + aarch64). Extract and run: 
tar -xzf CodexBarCLI-v0.17.0-linux-x86_64.tar.gz
./codexbar --version
./codexbar usage --format json --pretty

​
Build from Source

​
With Package Script

./Scripts/package_app.sh
# or
./Scripts/compile_and_run.sh
Bundles CodexBarCLI into CodexBar.app/Contents/Helpers/CodexBarCLI.

​
Standalone Build

swift build -c release --product CodexBarCLI
Binary at ./.build/release/CodexBarCLI.

​
Requirements

  • Swift 6.2+
  • Commander package (https://github.com/steipete/Commander)

​
Configuration

CodexBar reads ~/.codexbar/config.json for provider settings, secrets, and ordering. See Configuration for the schema.

​
Available Commands

The CLI provides several commands for managing and querying usage data:

usage

Fetch current usage data (default command)

cost

Print local token cost usage

config validate

Validate config file syntax

config dump

Print normalized config JSON

​
Global Flags

These flags work with all commands:
​
-h, --help
flag
Display help information
​
-V, --version
flag
Display version information
​
-v, --verbose
flag
Enable verbose logging
​
--no-color
flag
Disable ANSI colors in text output
​
--log-level
string
Set log level: trace, verbose, debug, info, warning, error, critical
​
--json-output
flag
Emit JSONL logs on stderr (machine-readable)
​
--json-only
flag
Suppress non-JSON output; errors become JSON payloads

​
Exit Codes

The CLI uses specific exit codes to indicate different failure modes:
CodeMeaning
0Success
1Unexpected failure
2Provider missing (binary not on PATH)
3Parse/format error
4CLI timeout

​
Notes

  • CLI uses the config file for enabled providers, ordering, and secrets
  • Reset lines follow the in-app reset time display setting when available (default: countdown)
  • Text output uses ANSI colors when stdout is a rich TTY; disable with --no-color or NO_COLOR/TERM=dumb
  • Copilot CLI queries require an API token via config apiKey or COPILOT_API_TOKEN
  • Prefer Codex RPC first, then PTY fallback; Claude defaults to web with CLI fallback when cookies are missing
  • OpenAI web requires a signed-in chatgpt.com session in Safari, Chrome, or Firefox. No passwords are stored; CodexBar reuses cookies
  • Safari cookie import may require granting CodexBar Full Disk Access (System Settings → Privacy & Security → Full Disk Access)

Build docs developers (and LLMs) love

Get started for freeTalk to us