> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage CLI
> Local token/cost usage reporting
Every time your agent runs with a session store, it records `total_tokens` and `cost` per session. `praisonai usage` reports those totals — no config, no network.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Sessions[💾 Sessions on disk] --> Usage[📊 praisonai usage]
Usage --> Table[✅ Aggregate table]
classDef store fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class Sessions store
class Usage process
class Table result
```
## Quick Start
Print the last 30 days, grouped by day.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage
```
Switch the grouping dimension with `--by`.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --by model
praisonai usage --by project
```
Limit the report to a time window with `--days` (`0` = all history).
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --days 7
praisonai usage --days 0
```
Produce machine-readable output for scripts.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --json
```
***
## How It Works
The command reads the current-project and global default session stores, filters by time window, groups the rows, then renders a table or JSON.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Store1[💾 Current project store] --> Collect[📥 Collect rows]
Store2[💾 Global default store] --> Collect
Collect --> Window[🗓 Filter by days]
Window --> Group[📊 Group by day/model/project]
Group --> Render[✅ Table or JSON]
classDef store fill:#6366F1,stroke:#7C90A0,color:#fff
classDef step fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class Store1,Store2 store
class Collect,Window,Group step
class Render result
```
| Behaviour | Detail |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Project buckets | Without `--project`, rows keep their origin — `current` and `global` show as separate buckets under `--by project`. |
| De-duplication | Sessions with the same `session_id` in both stores are counted once. |
| Scan limit | Each store is scanned up to 100,000 sessions. |
| Sort order | `--by day` is chronological; `--by model` and `--by project` are highest-spend-first. |
| Empty state | Prints `No usage recorded yet` when no rows and no errors. |
| Errors | A missing or damaged store prints `Usage may be incomplete: …` (table) or fills the `errors` array (JSON) — nothing is swallowed. |
| Cost source | Reads the pre-persisted `cost` field — no re-pricing. |
***
## Options
| Option | Short | Type | Default | Description |
| ----------- | ----- | ------ | ------- | ------------------------------------------------------------ |
| `--days` | `-d` | `int` | `30` | Only include sessions updated in the last N days (`0` = all) |
| `--by` | `-b` | `str` | `"day"` | Group by: `day`, `model`, or `project` |
| `--project` | `-p` | `str` | `None` | Restrict to a specific project ID |
| `--json` | — | `bool` | `False` | Emit machine-readable JSON |
An invalid `--by` value exits with code `1`.
***
## Which `--by` should I pick?
Pick the grouping that answers your question.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q[What do I want to know?] --> Trend{Spend over time?}
Trend -->|Yes| Day[--by day]
Trend -->|No| Which{Which model costs most?}
Which -->|Yes| Model[--by model]
Which -->|No| Proj[--by project]
classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class Q start
class Trend,Which decision
class Day,Model,Proj result
```
***
## JSON Output
`--json` prints a stable shape for dashboards and pipelines.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"by": "day",
"days": 30,
"project": null,
"rows": [ { "key": "2026-07-19", "total_tokens": 1200, "cost": 0.0034 } ],
"total_tokens": 1200,
"cost": 0.0034,
"errors": []
}
```
Table output shows cost to 4 decimal places (`$0.0034`); JSON rounds to 6.
***
## Common Patterns
Run a quick weekly review of spend by day.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --days 7
```
Audit which model costs the most across all history.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --by model --days 0
```
Feed a JSON report into a spreadsheet or dashboard.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --json > usage.json
```
***
## Best Practices
Rows only exist once agents run with a session store. Enable one with `memory="history"` or a `session_id` so `praisonai usage` has data to report.
A short window (`--days 7`) scans fewer sessions and returns quicker during active development.
Pipe `--json` into `jq` or a spreadsheet instead of parsing the table.
Passing `--project ` reads only that project's store — the `global` bucket is skipped.
***
## Related
Full command tree, including session commands
The session store these totals come from