Documentation
Getting started
From installing the CLI to reading your agent's day in the dashboard. Takes about ten minutes.
How it works
clioilc has two parts:
- The
clioilcCLI runs on the machine where you use your AI agent. It reads the agent's local session logs, keeps a copy in~/.clioilc/usage.db, and uploads new rows to your account. - The dashboard at dash.clioilc.com shows cost, tokens, errors and a timeline of every prompt, reply and tool call.
Everything works locally first: you can inspect your usage in the terminal before you
connect an account, and nothing leaves your machine until you run clioilc login.
Requirements
- macOS or Linux. (The background service needs launchd or systemd.)
- Claude Code, used at least once on this machine, so that session logs
exist in
~/.claude/projects. - Rust 1.89 or newer to build the CLI. Install it from rustup.rs if
cargo --versiondoesn't work. - A GitHub account to sign in to the dashboard.
1. Install the CLI
Build and install the latest version from GitHub:
cargo install --git https://github.com/PUYUP/clioilc-tracker clioilc --lockedThis puts clioilc in ~/.cargo/bin, which rustup adds to your PATH. Check that it works:
clioilc --helpTo update later, run the same cargo install command again with --force.
2. Try it locally
Read your existing Claude Code history into ~/.clioilc/usage.db. It's safe to
run again: records are never counted twice.
clioilc usage importThen look at it:
# tokens and errors per day (or --by model / --by project)
clioilc usage report --by day
# what the agent did today: prompts, replies and tool calls
clioilc activity
# another day, with the agent's thinking and full text
clioilc activity --date 2026-11-14 --thinking --fullNothing is uploaded yet. Prompts, replies and tool details are stored on this machine with secrets (API keys, tokens, passwords in common formats) redacted.
3. Connect to your account
clioilc login --server https://api.clioilc.comThe CLI prints a code and opens your browser:
Open: https://dash.clioilc.com/device
Code: ABCD-EFGH
waiting for approval (Ctrl+C to cancel) ...- Sign in with GitHub in the browser.
- Check that the device name and the code match what your terminal shows, then click Allow. Only allow codes you just requested yourself.
- Go back to the terminal. The login finishes on its own.
The first time you log in, the CLI asks how your private data (prompts, replies, thinking, tool details, project names) should be stored. You can't change this later.
| Server-side encryption | End-to-end encryption | |
|---|---|---|
| Who encrypts | The server, at rest | Your machine, before upload |
| Can the server read it? | Yes | No |
| Lost passphrase or laptop | Nothing lost | Private data is unrecoverable |
| In the dashboard | Just sign in | Enter your passphrase to unlock |
Choose at the prompt, or pass it up front with --mode server or --mode e2e. End-to-end asks for a passphrase of at least 12 characters; keep it
somewhere safe.
Options: --name "Work laptop" sets the device name shown in the dashboard
(default: the hostname). --no-browser skips opening the browser.
4. Upload your history
clioilc syncsynced 2385 message(s), 2568 tool call(s), 4154 private row(s) to https://api.clioilc.comUploads go in batches and can be repeated safely. If the network drops, the next sync sends whatever didn't make it.
5. Keep it running
Install the background service so new activity is recorded and uploaded automatically:
clioilc service install
clioilc service statusThe service runs clioilc watch --sync at every login and restarts it if it
stops. New activity reaches the dashboard within about 30 seconds. It uses a LaunchAgent
on macOS and a systemd --user unit on Linux, and logs to ~/.clioilc/watch.log.
# what it's doing, plus the last log lines
clioilc service status
# stop and remove it
clioilc service uninstallPrefer a terminal window? clioilc watch --sync does the same in the
foreground; stop it with Ctrl+C. Don't run both at once.
6. Use the dashboard
Open dash.clioilc.com and sign in with GitHub.
Overview
- Calendar of the last 12 months: tool calls that succeeded and failed per day. Click a day to open its activity; a click in the failed row opens just the errors.
- Cost, messages, tokens and tool calls for the last 24 hours, 7, 30 or 90 days, hourly or daily. Click a column to open that day.
- Cost by project and by model, to see where the spend goes.
Activity
- One day at a time, newest first, grouped by session, with the cost of each session.
- Filter by type (You, Agent, Thinking, Tool) and status (Succeeded, Error), by project, or search the text.
- With end-to-end encryption, enter your passphrase once per tab. Decryption happens in your browser.
Devices
Every connected machine, whether it synced in the last 5 minutes, and how much it sent. Revoke stops a machine from uploading right away; data it already sent stays.
More machines
Repeat steps 1, 3, 4 and 5 on each machine. Its data joins the same dashboard.
If that machine already has a local usage.db, the login moves it aside
(usage.db.before-login-…) and rebuilds it from the agent logs, so that the same
project counts as one project across machines. Stop any running clioilc watch on it first. History whose logs were already deleted stays only in that backup.
Privacy & encryption
- Statistics (model, token counts, status, tool names, time) are stored with hashed ids: no file paths, project names, branches or text.
- Private data (prompts, replies, thinking, tool summaries, error output, project names) is encrypted at rest, server-side or end-to-end as you chose, and only ever shown to you.
- Secrets in common formats are redacted on your machine before anything is stored, and long text is cut to a maximum length.
- Your device token lives in
~/.clioilc/auth.json, readable only by you. It can upload data, but it can't read your activity or statistics back.
Troubleshooting
not logged in; run `clioilc login --server <url>` first- Run step 3. The background service also needs a login before it can be installed.
this device was revoked or logged out; run `clioilc login`- The device was revoked in the dashboard. Log in again to reconnect it.
usage.db was hashed with a different salt than your account- The local database doesn't belong to this account (for example, a copy from another
machine). Run
clioilc loginagain; it rebuilds the database for you. wrong passphrase- The end-to-end passphrase didn't unlock your keys. Passphrases can't be reset; try the exact one you chose on your first login.
another `clioilc sync` is running- The background service is already syncing. Nothing to do.
- Nothing new shows up in the dashboard
- Run
clioilc service status. If it isn't running, runclioilc service installagain; the last log lines usually say why it stopped. A manualclioilc syncalso reports any error directly.
Uninstall
# stop the background service
clioilc service uninstall
# revoke this machine and remove its login (local data is kept)
clioilc logout
# remove local data and the CLI
rm -r ~/.clioilc
cargo uninstall clioilcCommand reference
clioilc usage import | Read existing agent logs into the local database |
clioilc usage report --by day|model|project | Token and error totals in the terminal |
clioilc activity [--date] [--project] [--thinking] [--full] | What the agent did on a day |
clioilc login --server <url> [--mode server|e2e] [--name] | Connect this machine to your account |
clioilc sync | Upload everything not yet on the server |
clioilc watch --sync | Record new activity and upload it every 30 s (foreground) |
clioilc service install|status|uninstall | Run watch --sync in the background at login |
clioilc logout | Revoke this machine and forget the login |
Every command accepts --data-dir <dir> (default ~/.clioilc)
and --help. Source and full CLI documentation: github.com/PUYUP/clioilc-tracker.