Quickstart
You should reach a useful dashboard with zero configuration. This page shows the happy path and the keys you need to know.
1. Start the daemon
The daemon is the background process that polls providers, ingests agent hooks, and persists data to SQLite. The TUI reads from it.
openusage telemetry daemon install
This takes about five seconds. It registers a launchd agent (macOS) or a systemd user unit (Linux) and starts the service. Verify with:
openusage telemetry daemon status
2. Run the dashboard
openusage
That's it. OpenUsage:
- Scans your environment for AI-tool API keys (e.g.
OPENAI_API_KEY,OPENROUTER_API_KEY) - Looks for installed binaries and config dirs (e.g.
claude,cursor,~/.codex) - Registers a provider account for each thing it finds
- Connects to the daemon over its Unix socket and renders the read model
If a provider doesn't show up, it's almost always because the env var or binary isn't where OpenUsage looks. See Provider not detected.
3. Move around
The defaults you'll use most often:
| Key | Action |
|---|---|
| Tab / Shift+Tab | Switch screens (Dashboard ↔ Analytics) |
| ↑ ↓ or j k | Move cursor |
| ← → or h l | Navigate panels / sections |
| Enter | Open a provider's detail view |
| Esc | Back / clear filter |
| r | Refresh all providers |
| / | Filter providers |
| v | Cycle dashboard view (Grid → Stacked → Tabs → Split → Compare) |
| w | Cycle time window (today / 3d / 7d / 30d / all) |
| c | Cycle cost visibility for focused tile (auto → hide → show → auto, persists per-account) |
| t | Cycle theme |
| , | Open settings |
| ? | Help overlay |
| q | Quit |
Full list: Keybindings reference.
4. Read a tile
Each tile shows:
- A status badge in the corner —
OK ●,WARN ◐,LIMIT ◌,AUTH ◈,ERR ✗,UNKNOWN ◇ - The provider name and account ID
- The primary metric (spend, credits, or quota)
- A gauge bar colored green → yellow → red as you approach a limit
- Tokens and model mix when the provider exposes them
- A sparkline of recent activity
Press Enter on a tile to open the full detail view: per-model breakdowns, charts, billing periods, and trends.
5. Add an API key
Most cloud providers need an env var. The catalog in Providers lists each one. For example:
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export OPENROUTER_API_KEY=sk-or-...
openusage
You can also paste keys interactively from the API Keys tab in the settings modal (,) — OpenUsage stores them as plain values that get loaded next session.
6. Install agent integrations
For richer per-session detail from Claude Code, Codex, and OpenCode, install their hooks. They post each turn directly to the daemon, giving you per-message data that polling alone cannot see.
openusage integrations install claude_code # if you use Claude Code
openusage integrations install codex # if you use Codex CLI
openusage integrations install opencode # if you use OpenCode
See the Daemon overview for what each integration captures.
What's next
- First-run walkthrough — annotated tour of the UI
- Concepts — mental model
- Customization — themes, keybindings, widget layout