CLI reference

Hermes Usage Insights ships a single CLI entry point: hui.

It is designed around a local SQLite database plus subcommands for ingestion, reporting, search, export, and plotting.

Global option

All commands accept:

hui --db PATH ...

• --db sets the SQLite database path
• if the database does not exist yet, the repository layer initializes it automatically on connect
• hui init is still the explicit setup command when you want to create the DB deliberately before other operations

Setup

uv sync

Command map

init

Initialize the SQLite database explicitly.

uv run hui --db usage.db init

Typical output:

initialized: usage.db

demo-data

Insert deterministic demo events so you can verify reports, search, plots, and exports before wiring real Hermes data.

uv run hui --db usage.db demo-data

Typical output:

seeded demo data

ingest-jsonl

Consume newline-delimited JSON usage events.

uv run hui --db usage.db ingest-jsonl path/to/events.jsonl

Typical output:

ingested: 42

Behavior notes:

• event ids are deterministic when omitted by the caller
• repeated ingests of the same event stream do not duplicate stored rows

import-hermes

Import Hermes cumulative totals from state.db plus transcript-derived tool-call events.

uv run hui \
  --db artifacts/hermes-usage.db \
  import-hermes \
  --hermes-home /path/to/hermes-home

Typical output:

imported: 18

Behavior notes:

• prefers state.db when present
• falls back to sessions.json totals when needed
• imports session deltas incrementally
• imports transcript tool-call events idempotently

watch-hermes

Continuously import Hermes totals and transcript tool calls on a polling interval.

uv run hui \
  --db artifacts/hermes-usage.db \
  watch-hermes \
  --hermes-home /path/to/hermes-home \
  --interval-seconds 60

Useful flags:

• --interval-seconds FLOAT — polling interval, default 60.0
• --iterations INT — optional bounded iteration count for tests or smoke runs

Bounded test example:

uv run hui \
  --db artifacts/hermes-usage.db \
  watch-hermes \
  --hermes-home /path/to/hermes-home \
  --interval-seconds 5 \
  --iterations 2

Behavior notes:

• prints an imported: N line after each polling cycle
• exits cleanly after the bounded iteration count when --iterations is used
• prints stopped on keyboard interrupt

report summary

Show high-level totals across the database.

uv run hui --db usage.db report summary
uv run hui --db usage.db report summary --since 2026-04-09 --until 2026-04-10

Use this first when you want to know whether the database is populated and roughly what is inside it.

Useful flags:

• --since YYYY-MM-DD — include events on or after the given day
• --until YYYY-MM-DD — include events on or before the given day

report breakdown

Show grouped breakdowns by one dimension.

uv run hui --db usage.db report breakdown --by tool
uv run hui --db usage.db report breakdown --by skill
uv run hui --db usage.db report breakdown --by session
uv run hui --db usage.db report breakdown --by model
uv run hui --db usage.db report breakdown --by day
uv run hui --db usage.db report breakdown --by provider
uv run hui --db usage.db report breakdown --by source

Supported values for --by:

• tool
• skill
• session
• model
• day
• provider
• source

Useful flags:

• --since YYYY-MM-DD — include events on or after the given day
• --until YYYY-MM-DD — include events on or before the given day

Interpretation note:

• in collector mode, --by tool is best understood as tool frequency unless the upstream event source emitted exact tool-level token counts

search

Search stored event text.

uv run hui --db usage.db search "browser_navigate"
uv run hui --db usage.db search "failing test" --limit 10
uv run hui --db usage.db search "browser_navigate" --since 2026-04-09 --until 2026-04-10

Useful flags:

• --limit INT — maximum number of returned rows, default 20
• --since YYYY-MM-DD — include events on or after the given day
• --until YYYY-MM-DD — include events on or before the given day

Output format:

• tab-separated lines containing timestamp, session id, tool name, skill name, total tokens, and notes

Behavior notes:

• search is normalized substring matching over stored event text
• it is intentionally simpler than a full-text search engine

plot daily-tokens

Render a PNG showing daily token totals.

mkdir -p artifacts
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png
uv run hui --db usage.db plot daily-tokens --since 2026-04-09 --until 2026-04-10 --output artifacts/daily-window.png

Useful flags:

• --since YYYY-MM-DD — include events on or after the given day
• --until YYYY-MM-DD — include events on or before the given day

Typical output:

wrote: artifacts/daily.png

export csv

Export stored events as a flat CSV.

mkdir -p artifacts
uv run hui --db usage.db export csv --output artifacts/usage.csv
uv run hui --db usage.db export csv --since 2026-04-09 --until 2026-04-10 --output artifacts/usage-window.csv

Useful flags:

• --since YYYY-MM-DD — include events on or after the given day
• --until YYYY-MM-DD — include events on or before the given day

Typical output:

wrote: artifacts/usage.csv

Typical workflows

Local proof with demo data

uv sync
uv run hui --db usage.db demo-data
uv run hui --db usage.db report summary
uv run hui --db usage.db report breakdown --by tool
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png

One-shot Hermes backfill

uv run hui \
  --db artifacts/hermes-usage.db \
  import-hermes \
  --hermes-home /path/to/hermes-home
uv run hui --db artifacts/hermes-usage.db report summary
uv run hui --db artifacts/hermes-usage.db export csv --output artifacts/hermes-usage.csv

Continuous no-source-change collector

uv run hui \
  --db artifacts/hermes-usage.db \
  watch-hermes \
  --hermes-home /path/to/hermes-home \
  --interval-seconds 60

JSONL ingestion path

uv run hui --db usage.db ingest-jsonl path/to/events.jsonl
uv run hui --db usage.db report breakdown --by model
uv run hui --db usage.db search "browser_navigate"

Common misconceptions

• init is explicit setup, but most commands can initialize the database automatically when they connect.
• watch-hermes is not the same as richer event attribution; it is the continuous version of collector mode.
• search is intentionally simple substring matching, not a fuzzy or ranked search engine.