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 clioilc CLI 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.

Supported agents today: Claude Code. Readers for other agents are on the way.

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 --version doesn't work.
  • A GitHub account to sign in to the dashboard.

1. Install the CLI

Build and install the latest version from GitHub:

Terminal
cargo install --git https://github.com/PUYUP/clioilc-tracker clioilc --locked

This puts clioilc in ~/.cargo/bin, which rustup adds to your PATH. Check that it works:

Terminal
clioilc --help

To 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.

Terminal
clioilc usage import

Then look at it:

Terminal
# 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 --full

Nothing 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

Terminal
clioilc login --server https://api.clioilc.com

The CLI prints a code and opens your browser:

Output
  Open:  https://dash.clioilc.com/device
  Code:  ABCD-EFGH

waiting for approval (Ctrl+C to cancel) ...
  1. Sign in with GitHub in the browser.
  2. Check that the device name and the code match what your terminal shows, then click Allow. Only allow codes you just requested yourself.
  3. 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 encryptionEnd-to-end encryption
Who encryptsThe server, at restYour machine, before upload
Can the server read it?YesNo
Lost passphrase or laptopNothing lostPrivate data is unrecoverable
In the dashboardJust sign inEnter 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

Terminal
clioilc sync
Output
synced 2385 message(s), 2568 tool call(s), 4154 private row(s) to https://api.clioilc.com

Uploads 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:

Terminal
clioilc service install
clioilc service status

The 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.

Terminal
# what it's doing, plus the last log lines
clioilc service status

# stop and remove it
clioilc service uninstall

Prefer 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.
Cost is the Claude API price of your tokens, not your bill. If you use Claude Code through a subscription, it shows what the same work would cost on the API.

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 login again; 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, run clioilc service install again; the last log lines usually say why it stopped. A manual clioilc sync also reports any error directly.

Uninstall

Terminal
# 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 clioilc

Command reference

clioilc usage importRead existing agent logs into the local database
clioilc usage report --by day|model|projectToken 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 syncUpload everything not yet on the server
clioilc watch --syncRecord new activity and upload it every 30 s (foreground)
clioilc service install|status|uninstallRun watch --sync in the background at login
clioilc logoutRevoke 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.