Commands, routes, sources, and local state.
Use this page when you already know what you want to do. For a first setup, start with the beginner walkthrough instead.
CLI commands
| Command | Purpose |
|---|---|
fleetlens start [--port N] [--open] [--no-daemon] | Start the local dashboard and, unless skipped, the usage daemon. |
fleetlens stop | Stop the local dashboard and daemon. |
fleetlens status | Show server, daemon, port, version, and latest snapshot state. |
fleetlens update | Install the latest published CLI and restart stale services. |
fleetlens web [page] [--open] | Open a dashboard page without managing the daemon. |
fleetlens runs [--watch] [--json] [--since 24h] | Live local LLM call activity and token spend in the terminal. |
fleetlens usage [--save] | Print a live Claude Code plan-utilization snapshot in the terminal as colored progress bars — 5-hour and 7-day windows, plus Opus, Sonnet, OAuth-app, and Cowork breakdowns and any pay-as-you-go extra usage. --save also records this snapshot to local history and, in the background, saves one for every other configured provider (Codex, Copilot, Grok, Z.ai) even though their windows aren't part of this terminal view. |
fleetlens usage --history [-s D] [--days N] | Print historical usage and cost rows. |
fleetlens entries --day D|--session ID|--all | Inspect day-scoped local perception entries. |
fleetlens digest day [--date D|--today] [--force] [--json]fleetlens digest week [--week D|--this-week] [--force] [--json]fleetlens digest month [--month YYYY-MM|--this-month] [--force] [--json] | Generate or read a day, week, or month digest from the terminal — the same narrative shown at /day and /insights. Without a date flag, each targets the last completed period (cached to disk); --today/--this-week/--this-month target the still-running current period instead. --force regenerates past a cached result. --json prints the same structure the dashboard reads. |
fleetlens daemon start|stop|status|logs | Manage the usage and team-sync worker separately. |
fleetlens team join <url> <token> | Pair a local machine and open the browser onboarding flow. |
fleetlens team status|sync|backfill|logs|leave | status reports pairing details and actively checks the connection, so a revoked token shows up immediately instead of waiting for the next scheduled sync. sync pushes activity right now rather than waiting for the next cycle. backfill force-reuploads your full local plan-utilization history — useful when the team dashboard's history views need to be repopulated. logs shows the outcome of recent sync attempts. leave unpairs this machine; local data is unaffected. |
fleetlens autostart install|uninstall|status | Manage daemon start at login on supported macOS setups. |
fleetlens menubar install|uninstall|open|stop|status [--no-open] [--no-login] | Manage the optional native macOS usage widget. install places it in Applications, opens it, and registers it to launch at login; --no-open installs quietly and --no-login skips the login registration. The Settings page has matching Install/Open/Uninstall buttons, but an install triggered from there always skips login registration — use the terminal command if you want the widget to start automatically at login. A dismissible dashboard banner also offers to install it the first time it notices the widget isn't set up. |
Dashboard routes
| Route | Use it for |
|---|---|
/ | Overview metrics, heatmap, daily activity, projects, and recent sessions. |
/sessions | Search and inspect all normalized sessions. |
/sessions/[id] | Open rich detail for one session: timeline, tools, tokens, gaps, workflows, and shipping signals. |
/projects | Canonical project rollups and worktree context. |
/projects/[slug] | Inspect one project's sessions, activity, and local folder context. |
/day | Open daily activity, the timeline, idle gaps, and concurrency. |
/usage | Historical provider utilization. |
/insights | Review a structured weekly retrospective when entries and AI features are available. |
/digest, /parallelism | Older links, kept for bookmarks — both redirect straight into /day (/parallelism lands on its timeline section). |
/agent | Ask questions over local history and create handoffs. |
/runs | Watch live local LLM runs and their streamed events. |
/settings | Local service, menu bar, credentials, and AI settings. |
/team | Pairing, sync activity, project selection, and data boundary. |
/team/onboarding | Three-step member setup after a browser-based join. |
/changelog | Review user-facing changes in the installed product. |
Team Edition surfaces
| Route | Use it for |
|---|---|
/team/[slug] | Admin roster, combined activity, selectable ranges, and live refresh. |
/team/[slug]/members/[id] | Member activity, plan fit, daemon freshness, and daily rollups. |
/team/[slug]/groups | Create and manage groups, memberships, and manager scope. |
/team/[slug]/groups/[group] | Open a group-scoped activity view and its settings. |
/team/[slug]/groups/[group]/insights | Review group-level insights and delivery context. |
/team/[slug]/plan | Compare plan utilization, cycle pace, peaks, and capacity. |
/team/[slug]/settings | Manage team settings and optional GitHub, Jira, and Linear integrations. |
/report/[slug] | Open a shared report or its printable output. |
Supported local sources
| Source | Typical root | Notes |
|---|---|---|
| Claude Code | ~/.claude/projects | Sessions, transcripts, usage, projects, and signals. |
| Codex | ~/.codex/sessions | Sessions, transcripts, projects, and available usage. |
| GitHub Copilot CLI | ~/.copilot/session-state + authenticated local SDK RPC | Sessions, transcripts, tools, token totals, code changes, projects, and monthly AI-credit utilization. |
| Gemini CLI | ~/.gemini/tmp | Session analytics and detail. |
| Antigravity | ~/.gemini/antigravity-cli | Session analytics and detail. |
| Cowork | Local Cowork mirror | Session analytics and detail. |
| Grok Build | ~/.grok/sessions or GROK_HOME | Sessions and available usage. |
| Z.ai | Configured API key | Usage-only source; it is not a transcript adapter. |
Plan-utilization coverage
Fleetlens polls each source's plan-utilization data independently — a missing or expired credential for one source never slows or hides the others on /usage or the menu bar widget. (The sidebar's current-usage gauge only ever shows Claude Code.)
| Source | Usage tracked | Windows shown |
|---|---|---|
| Claude Code | Yes | 5-hour and 7-day, plus separate 7-day figures for Opus, Sonnet, OAuth apps, and Cowork, and optional pay-as-you-go extra usage. |
| Codex | Yes | 5-hour and 7-day. |
| GitHub Copilot CLI | Yes | Monthly AI-credit or premium-request allowance only — no 5-hour or 7-day window. |
| Grok Build | Yes | 7-day shared pool only — no 5-hour window. |
| Z.ai | Yes | 5-hour and 7-day token windows, plus a separate monthly web-search meter. |
| Gemini CLI | No | Session activity only. |
| Antigravity | No | Session activity only. |
| Cowork | No | Session activity only — usage already counts against the paired Claude Code account above. |
Gemini CLI and Antigravity don't expose plan-utilization data to poll — this is a deliberate omission, not a temporary gap.
Environment variables
| Variable | Default | Purpose |
|---|---|---|
CCLENS_PORT | 3321 | Default local dashboard port. |
CCLENS_HOME | ~/.cclens | Local Fleetlens state directory. |
GROK_HOME | ~/.grok | Alternate Grok Build home. |
NEXT_OUTPUT | unset | Set to standalone when building the bundled web app. |
Team Edition server environment
These configure the self-hosted team-server (Docker image). The deploy guides pre-wire them; defaults and generation commands live in each path's README in deploy/.
| Variable | Required | Purpose |
|---|---|---|
DATABASE_URL | Yes | Postgres connection string; migrations run against it automatically on boot. |
BASE_URL | Yes | Public base URL of the deployed server; used for pairing links and redirects. |
FLEETLENS_ENCRYPTION_KEY | Yes | Encrypts integration credentials (GitHub, Jira, Linear, email) at rest. Keep it stable — rotating it makes stored credentials unreadable. |
FLEETLENS_EXTERNAL_SCHEDULER | No | Set to 1 to disable the in-process scheduler when running an external cron. |
FLEETLENS_SCHEDULER_SECRET | No | Shared secret for the external scheduler endpoint. |
Local state
~/.cclens/
pid
daemon.pid
usage.jsonl
daemon.log
autostart.json
entries/
digests/
agent-index/
team-config.jsonProvider transcript roots remain under the provider's own home directory. See the privacy model before inspecting or sharing any local file.
Need help choosing a command?
Run fleetlens help in the installed build for the exact flags supported by your version.