reference
statusbar CLIEvery status page you care about, from the terminal. The CLI ships inside StatusBar.app and reads the same live snapshot the app maintains — no network, no waiting.
setup
statusbar on your PATHIf you installed with Homebrew, you’re already done — the cask links the command for you. Otherwise it’s one click in the app.
brew install --cask alexnodeland/tap/statusbarDirect download? Open Settings → General → statusbar CLI → Install. One click, one admin prompt, done.
statusbar --version # "statusbar 0.4.0"
statusbar help # full usagesudo ln -sf /Applications/StatusBar.app/Contents/MacOS/statusbar-cli \
/usr/local/bin/statusbarThe app refreshes its snapshot on every poll; status and prompt read it instantly. If the app isn’t running, --fresh fetches live from providers and wait always polls live.
commands
| Command | What it does |
|---|---|
status [name] | Current status for all sources, or one by name (case-insensitive, substring match). Reads the cache; exits 0 when all clear, 1 on issues. |
list | Alias for status. |
wait <name> | Block until the source is operational again, polling the provider live. Gate a deploy: statusbar wait npm && npm publish. |
prompt | One compact glyph for shell prompts: ● when clear, ▲1 when one source has issues, ✖2 at critical. Honors .statusbar repo scoping. |
refresh | Ask the running app to refresh all sources now (via the statusbar:// URL scheme). |
open [name] | Open the popover, optionally focused on a source. |
add <url> [name] | Add a status page through the app. |
remove <name> | Remove a source through the app. |
cache-path | Print the status cache location. |
version | Print the StatusBar version. Also --version / -v. |
help | Show usage. Also --help / -h. |
statusbar status # every source, colored, one line each
statusbar status github # just GitHub
statusbar status --json | jq . # machine-readable snapshot
statusbar status --fresh # bypass the cache, fetch live
statusbar wait npm && npm publish # block until npm recovers
statusbar wait api --timeout 600 --interval 15
statusbar prompt # "●" or "▲1" for your prompt
statusbar add https://status.openai.com OpenAIoptions
| Flag | Applies to | Effect |
|---|---|---|
--json | status | Machine-readable output: the full snapshot, or one source as a flat object. |
--fresh | status | Fetch live from each provider instead of reading the cache. Works without the app running. |
--all | status, prompt | Ignore a .statusbar repo scope and show every source. |
--timeout <sec> | wait | Give up after N seconds. Default 1800. |
--interval <sec> | wait | Poll every N seconds. Default 30, minimum 5. |
signals
Both are stable interfaces — script against them.
0 | All monitored sources operational |
1 | At least one source has issues |
2 | Unknown status, no cache yet, or no source matched |
64 | Usage error or unknown command |
● | Operational (green) |
▲ | Minor outage (yellow) / major outage (orange) |
✖ | Critical outage (red) |
○ | Unknown (gray) |
Colors turn off automatically when output is piped, or when NO_COLOR is set.
scoping
.statusbarDrop a .statusbar file in a repo and status/prompt report only that project’s upstream dependencies. The CLI walks up from the working directory to find it — like .gitignore.
# .statusbar — upstream deps for this repo
# one source name per line
GitHub
npm
VercelNames match case-insensitively against your monitored sources. A name you don’t monitor yet prints a hint: not monitored — statusbar add <url> npm. Pass --all to see everything regardless.
With scoping, statusbar prompt in a Starship or tmux status line shows the health of the repo you’re standing in — not your whole watchlist. Copy-paste configs for Starship, tmux, and SketchyBar are in the integration guides.