> ## 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
> Zero-config local token and cost reporting across all your sessions
See what you've spent โ no dashboard, no API key, no setup. `praisonai usage` reads the token and cost totals PraisonAI already saves per session and rolls them up by day, model, or project.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "praisonai usage"
A["๐ Session Store"] --> B["๐ Filter --days --project"]
B --> C["๐ Group --by day/model/project"]
C --> D["โ
Table or JSON"]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class A input
class B,C process
class D output
```
## Quick Start
Run one line to see the last 30 days grouped by day.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage
```
```
Usage
โโโโโโโโโโโโโโณโโโโโโโโโโณโโโโโโโโโโ
โ Day โ Tokens โ Cost โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ 2026-07-19 โ 1,240 โ $0.0140 โ
โ 2026-07-20 โ 3,980 โ $0.0320 โ
โ Total โ 5,220 โ $0.0460 โ
โโโโโโโโโโโโโโดโโโโโโโโโโดโโโโโโโโโโ
```
Switch the grouping to see spend by model or by project.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --by model
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --by project
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --days 7
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --project my-app
```
Add `--json` for machine-readable output you can pipe to `jq`.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --json
```
This command reads data that `praisonai run` already saved to disk โ no setup, no re-instrumentation, no external observability platform.
***
## Choose Your Grouping
Pick the `--by` value that matches the question you're asking.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{What are you trying to see?} --> D[Spend over time]
Q --> M[Which model costs most]
Q --> P[Which project costs most]
D --> DayCmd[praisonai usage --by day]
M --> ModelCmd[praisonai usage --by model]
P --> ProjCmd[praisonai usage --by project]
classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
classDef branch fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef cmd fill:#10B981,stroke:#7C90A0,color:#fff
class Q q
class D,M,P branch
class DayCmd,ModelCmd,ProjCmd cmd
```
***
## How It Works
`praisonai usage` reads the same session files that `praisonai session list` shows โ nothing new is written, no external service is contacted.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI as praisonai usage
participant Proj as Current-project store
participant Glob as Global default store
User->>CLI: praisonai usage --by model --days 7
CLI->>Proj: list_sessions()
Proj-->>CLI: sessions (total_tokens, cost, model, updated_at)
CLI->>Glob: list_sessions()
Glob-->>CLI: sessions
CLI->>CLI: filter by --days, de-dup, group by --by
CLI-->>User: table (or JSON if --json)
classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
classDef cli fill:#189AB4,stroke:#7C90A0,color:#fff
classDef store fill:#10B981,stroke:#7C90A0,color:#fff
class User user
class CLI cli
class Proj,Glob store
```
| Source | What it contributes |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| Current-project session store | Sessions from the project you're in โ labelled `current` under `--by project`. |
| Global default session store | Sessions from the global store โ labelled `global` under `--by project`. |
| `--project ` | Restricts to exactly that project's store; its own ID becomes the sole `project` label. |
When `--project` is omitted, both stores are scanned separately and session ids shared across them are de-duplicated (the current-project store wins). Each store is scanned up to 100,000 sessions to keep memory predictable โ realistic stores are never truncated.
| Behaviour | Detail |
| ------------- | --------------------------------------------------------------------------------------- |
| Time window | `--days` filters on `updated_at`; values without a timezone are treated as UTC |
| Sorting | `--by day` is chronological; `--by model` / `--by project` sort by highest tokens first |
| Grouping keys | Unknown model โ `unknown`; unparseable date โ `unknown`; empty project โ `current` |
| Total row | The table always appends a `Total` row |
| Zero values | Render as `-`; tokens are comma-formatted; cost is `$X.XXXX` |
***
## Options
Every option is optional โ `praisonai usage` with no flags reports the last 30 days by day.
| Option | Short | Type | Default | Description |
| ----------- | ----- | ------ | ------- | ------------------------------------------------------------------------------------- |
| `--days` | `-d` | `int` | `30` | Only include sessions updated in the last N days. `0` = no time filter (include all). |
| `--by` | `-b` | `str` | `"day"` | Group by: `day`, `model`, or `project`. Any other value exits with an error. |
| `--project` | `-p` | `str` | `None` | Restrict to a specific project ID (reads only that project's scoped store). |
| `--json` | | `bool` | `False` | Emit machine-readable JSON (also auto-enabled by the CLI's global JSON output mode). |
`--by day` sorts chronologically (ascending); `--by model` and `--by project` sort by tokens descending (highest spend first).
### JSON output shape
`--json` emits a stable object you can pipe into dashboards or cron jobs.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --by day --days 30 --json
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"by": "day",
"days": 30,
"project": null,
"rows": [
{"key": "2026-07-15", "total_tokens": 12340, "cost": 0.043},
{"key": "2026-07-18", "total_tokens": 5220, "cost": 0.014}
],
"total_tokens": 17560,
"cost": 0.057,
"errors": []
}
```
### Empty output
* Table: `No usage recorded yet`
* JSON: `{"rows": [], "total_tokens": 0, "cost": 0.0, ...}`
### Store errors
A missing or damaged store is non-fatal. Table mode prints `Usage may be incomplete: ` as a warning; JSON mode exposes the reasons under `errors`. The command still exits `0` and returns whatever it could read โ a broken store is never silently reported as empty. An invalid `--by` value exits `1` with `--by must be one of: day, model, project`.
***
## Common Patterns
Practical one-liners for everyday reviews.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Weekly review by model
praisonai usage --days 7 --by model
# CI cost snapshot
praisonai usage --json | jq '.cost'
# Full history by project (no time filter)
praisonai usage --days 0 --by project
# Export 90 days to CSV
praisonai usage --days 90 --by day --json | jq '.rows[] | [.key, .total_tokens, .cost] | @csv' -r > usage.csv
```
***
## Grouping Modes
| Mode | Sorts by | Use it to |
| -------------- | ------------------- | -------------------------------- |
| `--by day` | Chronological | See a spend trend over time. |
| `--by model` | Highest spend first | Find which model costs the most. |
| `--by project` | Highest spend first | Compare spend across workspaces. |
***
## Best Practices
Run `praisonai usage --by model` โ models are sorted by highest token count first, so the biggest spenders appear at the top.
Use `praisonai usage --days 0` to disable the time filter and aggregate every session on disk, not just the last 30 days. Use this sparingly on very large session directories, since it scans up to 100,000 records per store.
`praisonai usage --json` emits a stable shape (`by`, `days`, `project`, `rows`, `total_tokens`, `cost`, `errors`) that is safe to parse in CI or dashboards. The global JSON output mode auto-enables JSON, so scripts running under it get machine-readable output without passing `--json` explicitly.
Watch for `Usage may be incomplete` warnings. They mean a store could not be read fully โ check filesystem permissions on the session store path and look for corrupt records. The totals shown exclude that store rather than silently reporting zero. In `--json` mode the same reasons appear in the `errors` array.
Combine `--project my-app` with `--by model` to see which model drives spend inside one project.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --project my-app --by model
```
Pipe `--json` output to `jq` in CI to fail a build when spend crosses a threshold.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai usage --json | jq 'if .cost > 5 then error("over budget") else .cost end'
```
Cost only appears for models present in the default pricing table. See [Cost Tracking](/docs/docs/cli/cost-tracking) to add custom pricing.
Without `--project`, `--by project` splits usage into a `current` bucket (this project's store) and a `global` bucket (the default store). Shared session IDs appear once. Pass `--project my-app` to report a single project only.
***
## Related
Per-run and per-session cost source
The underlying session store
Per-run execution tracker
Performance metrics