> ## 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 > See how many tokens and how much money your agents are spending โ€” from your local machine. See exactly where your tokens (and dollars) are going โ€” no dashboard, no API key, no config. `praisonai usage` reads the same local session store that `praisonai session list` uses and rolls it up per day, per model, or per project. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR subgraph "Local usage report" Store[๐Ÿ’พ Session Store] --> Read[๐Ÿ“– Read totals] Read --> Group{๐Ÿ“Š Group by} Group -->|day| Day[๐Ÿ“… Day] Group -->|model| Model[๐Ÿค– Model] Group -->|project| Project[๐Ÿ“ Project] end classDef store fill:#189AB4,stroke:#7C90A0,color:#fff classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff classDef output fill:#10B981,stroke:#7C90A0,color:#fff class Store store class Read,Group process class Day,Model,Project output ``` ## Quick Start Show the last 30 days grouped by day: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage ``` ``` Usage โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“ โ”ƒ Day โ”ƒ Tokens โ”ƒ Cost โ”ƒ โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ โ”‚ 2026-07-15 โ”‚ 4,320 โ”‚ $0.0180 โ”‚ โ”‚ 2026-07-18 โ”‚ 12,500 โ”‚ $0.0512 โ”‚ โ”‚ Total โ”‚ 16,820 โ”‚ $0.0692 โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` Find your most expensive model: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --by model ``` *** ## Choose Your View Three groupings answer three different questions. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph TB Q{What do you want
to know?} -->|When did I spend?| Day[--by day] Q -->|Which model costs most?| Model[--by model] Q -->|Which project costs most?| Project[--by project] classDef q fill:#8B0000,stroke:#7C90A0,color:#fff classDef view fill:#189AB4,stroke:#7C90A0,color:#fff class Q q class Day,Model,Project view ``` Spot spend spikes over time. Rows sort chronologically. Find your most expensive model. Rows sort by highest spend first. Compare projects sharing one machine. Rows sort by highest spend first. *** ## Options ``` praisonai usage [--days N] [--by day|model|project] [--project ID] [--json] ``` | Option | Short | Type | Default | Description | | ----------- | ----- | ------ | -------- | ----------------------------------------------------------------- | | `--days` | `-d` | `int` | `30` | Only include sessions updated in the last N days (`0` = all time) | | `--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 instead of a table | *** ## Common Patterns Check last week only: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --days 7 ``` Break a single project down by model: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --project my-app --by model ``` Pipe into `jq` to flag expensive rows: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --json | jq '.rows[] | select(.cost > 1)' ``` The JSON output shape: ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "by": "model", "days": 30, "project": null, "rows": [ { "key": "gpt-4o", "total_tokens": 12500, "cost": 0.0512 }, { "key": "gpt-4o-mini", "total_tokens": 4320, "cost": 0.0180 } ], "total_tokens": 16820, "cost": 0.0692, "errors": [] } ``` *** ## How It Works `praisonai usage` reads the on-disk session store โ€” the same store surfaced by `praisonai session list`. No network calls, no configuration, no external observability platform. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant User participant CLI as praisonai CLI participant Store as Session store User->>CLI: praisonai run "task" (session active) CLI->>Store: accumulate token + cost totals Note over User: later... User->>CLI: praisonai usage --by model CLI->>Store: read totals (last N days) Store-->>CLI: per-session tokens + cost CLI-->>User: grouped table (or --json) classDef user fill:#6366F1,stroke:#7C90A0,color:#fff classDef cli fill:#8B0000,stroke:#7C90A0,color:#fff classDef store fill:#189AB4,stroke:#7C90A0,color:#fff ``` With no `--project`, both the current-project store and the global default store are read. Rows keep their originating identity (`current` or `global`), and a session that appears in both stores is counted once. | Behaviour | What happens | | -------------------- | --------------------------------------------------------------------------------------------------- | | `--days 0` | No time filter โ€” includes every session | | Empty store | Prints `No usage recorded yet` (no table) | | Store read failure | Reports `Usage may be incomplete: ...` (or an `errors` array in `--json`) instead of returning zero | | Invalid `--by` value | Exits with code `1` and a clear error | Costs come from the existing per-run `ModelPricing` tracker โ€” `usage` aggregates what was already recorded, it does not re-price. *** ## Best Practices Use `--days 7` for a fast look at the current week before it grows into a surprise bill. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --days 7 ``` Group by `model` to see which model drives your spend, then decide whether a cheaper one fits. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --by model ``` Use `--json` in cron or CI and act on the numbers with `jq`. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai usage --json | jq '.cost' ``` Numbers reflect only what was recorded to the local session store. For team-wide totals across machines, use an observability integration such as [Langfuse](/docs/docs/observability/langfuse). *** ## Related The session store this command reads from. Richer per-trace inspection. The in-run cost display this aggregates. Real-time token counters during a run.