easysvs-cli

Local Claude Code usage tracking — read ~/.claude/projects/ JSONL, summarize spend by model and project locally, and optionally sync to your self-hosted easysvs server for multi-machine ledgers.

easysvs-cli is the command-line companion to easysvs. It works fully offline for local cost reporting. Server sync is opt-in and only needed if you want to aggregate usage across multiple machines or share a team ledger.

Quickstart

npm install -g easysvs-cli
easysvs init        # browser opens for login; registers machine + installs auto-sync timer
easysvs status      # health check: last sync time, machine id, source adapter state

Auto-sync runs every 30 minutes in the background. To remove everything:

easysvs uninstall           # removes timer, hooks, and local config
npm uninstall -g easysvs-cli

Install

npm install -g easysvs-cli

Verify the install:

easysvs --help

Requires Node.js >= 20.

Quick start

Local-only (no server, no signup)

easysvs ledger status

This reads JSONL from ~/.claude/projects/ and computes a token + cost summary entirely on your machine. No network, no account, no telemetry.

You will see three time windows (today / this week / this month), plus a top-projects breakdown. Cost columns require a cached pricing snapshot — the first run may show — for cost; fetch pricing once with:

easysvs ledger refresh-pricing

Multi-machine sync (self-hosted easysvs server)

If you self-host the easysvs server (see the main repo README for docker compose up -d), the CLI can upload session events so all your machines roll up into one ledger:

easysvs login          # GitHub device flow, saves API token to ~/.easysvs/config.json
easysvs ledger sync    # uploads session events recorded since lastSyncAt

login opens a verification URL and prompts for a short user code (standard GitHub device authorization flow). On success the API token is persisted under ~/.easysvs/.

One-step onboarding

easysvs init

Detects your Claude Code install at ~/.claude/projects/, counts session files, and writes the local config enabling the ledger product. Useful as a first-run check.

Commands

| Command | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------- | | easysvs login | Authenticate via GitHub device flow and save API token to ~/.easysvs/config.json. | | easysvs init | Detect Claude Code install, count session files, and enable the ledger product locally. | | easysvs ledger status | Local cost report — today / week / month plus top projects, computed from ~/.claude/projects/. | | easysvs ledger sync | Upload session events recorded since lastSyncAt to your easysvs server (requires login). | | easysvs ledger refresh-pricing | Pull the latest model pricing snapshot from the server and cache it at ~/.easysvs/pricing.json. |

All commands accept -h, --help. The root command also accepts -V, --version. None of the current subcommands take additional flags; date filtering is fixed to today / week / month windows in ledger status.

How local cost estimation works

easysvs ledger status parses every JSONL session under ~/.claude/projects/<project>/<session-id>.jsonl, extracts usage fields (input / output / cache-read / cache-5m-write / cache-1h-write tokens), and multiplies by per-model rates from ~/.easysvs/pricing.json.

If no pricing cache exists, the CLI prints — in the cost column and runs in offline mode — token counts are still accurate. Run easysvs ledger refresh-pricing to enable cost figures. Server-side sync also returns an authoritative computedCostUsd per batch.

Configuration

After easysvs login, the API token is saved to ~/.easysvs/config.json. The CLI manages this file automatically — there is no need to edit it by hand.

To point the CLI at a non-default server (for example, a self-hosted instance on a different host), set:

export EASYSVS_SERVER=grpc.your-host.example.com:443

Files the CLI may create:

| Path | Purpose | | --------------------------- | -------------------------------------------------------- | | ~/.easysvs/config.json | API token, machine ID, last sync timestamp, products. | | ~/.easysvs/pricing.json | Cached model pricing snapshot used for local estimates. |

Privacy

Local commands (ledger status, init) never leave your machine. The sync command uploads only token counts, model names, project paths (as recorded by Claude Code), and timestamps — never prompt content or completions. You can inspect the exact payload at apps/cli/src/commands/ledger/sync.ts in the easysvs source tree.

License

MIT — see LICENSE.

Links

• Homepage: https://easysvs.com
• npm: https://www.npmjs.com/package/easysvs-cli