alice.mosphere.at
this repo has no description
1---
2summary: "CodexBar CLI for fetching usage from the command line."
3read_when:
4 - "You want to call CodexBar data from scripts or a terminal."
5 - "Adding or modifying Commander-based CLI commands."
6 - "Aligning menubar and CLI output/behavior."
7---
8
9# CodexBar CLI
10
11A lightweight Commander-based CLI that mirrors the menubar app’s data paths (Codex RPC → PTY fallback; Claude PTY).
12Use it when you need usage numbers in scripts, CI, or dashboards without UI.
13
14## Install
15- In the app: **Preferences → Advanced → Install CLI**. This symlinks `CodexBarCLI` to `/usr/local/bin/codexbar` and `/opt/homebrew/bin/codexbar`.
16- From the repo: `./bin/install-codexbar-cli.sh` (same symlink targets).
17- Manual: `ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar`.
18
19## Build
20- `./Scripts/package_app.sh` (or `./Scripts/compile_and_run.sh`) bundles `CodexBarCLI` into `CodexBar.app/Contents/Helpers/CodexBarCLI`.
21- Standalone: `swift build -c release --product CodexBarCLI` (binary at `./.build/release/CodexBarCLI`).
22- Dependencies: Swift 6.2+, Commander package (`https://github.com/steipete/Commander`).
23
24## Command
25- `codexbar` defaults to the `usage` command.
26 - `--format text|json` (default: text).
27 - `--provider codex|claude|both` (default: your in-app toggles; falls back to Codex).
28 - `--no-credits` (hide Codex credits in text output).
29 - `--pretty` (pretty-print JSON).
30 - `--status` (fetch provider status pages and include them in output).
31- Global flags: `-h/--help`, `-V/--version`, `-v/--verbose`, `--log-level <trace|verbose|debug|info|warning|error|critical>`, `--json-output`.
32
33## Example usage
34```
35codexbar # text, respects app toggles
36codexbar --provider claude # force Claude
37codexbar --format json --pretty # machine output
38codexbar --format json --provider both
39codexbar --status # include status page indicator/description
40```
41
42### Sample output (text)
43```
44Codex 0.6.0 (codex-cli)
45Session: 72% left
46Resets today at 2:15 PM
47Weekly: 41% left
48Resets Fri at 9:00 AM
49Credits: 112.4 left
50
51Claude Code 2.0.58 (claude)
52Session: 88% left
53Resets tomorrow at 1:00 AM
54Weekly: 63% left
55Resets Sat at 6:00 AM
56Sonnet: 95% left
57Account: user@example.com
58Plan: Pro
59```
60
61### Sample output (JSON, pretty)
62```json
63{
64 "provider": "codex",
65 "version": "0.6.0",
66 "source": "codex-cli",
67 "status": { "indicator": "none", "description": "Operational", "updatedAt": "2025-12-04T17:55:00Z", "url": "https://status.openai.com/" },
68 "primary": { "usedPercent": 28, "windowMinutes": 300, "resetsAt": "2025-12-04T19:15:00Z" },
69 "secondary": { "usedPercent": 59, "windowMinutes": 10080, "resetsAt": "2025-12-05T17:00:00Z" },
70 "tertiary": null,
71 "updatedAt": "2025-12-04T18:10:22Z",
72 "accountEmail": "user@example.com",
73 "accountOrganization": null,
74 "loginMethod": "plus",
75 "credits": { "remaining": 112.4, "updatedAt": "2025-12-04T18:10:21Z" }
76}
77```
78
79## Exit codes (proposed)
80- 0: success
81- 2: provider missing (binary not on PATH)
82- 3: parse/format error
83- 4: CLI timeout
84- 1: unexpected failure
85
86## Notes
87- CLI reuses menubar toggles when present (prefers `com.steipete.codexbar{,.debug}` defaults), otherwise defaults to Codex only.
88- Prefer Codex RPC first, then PTY fallback; Claude stays PTY-only.
89- Future: optional `--from-cache` flag to read the menubar app’s persisted snapshot (if/when that file lands).