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 — or reports per-tool reliability with --by tool.

Quick Start

1. See your spend

   Run one line to see the last 30 days grouped by day.

   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 │
   └────────────┴─────────┴─────────┘

2. Group differently

   Switch the grouping to see spend by model or by project.

   praisonai usage --by model

3. Group by project (current vs global stores)

   praisonai usage --by project

4. Last 7 days only

   praisonai usage --days 7

5. A single project

   praisonai usage --project my-app

6. Get JSON for scripts

   Add --json for machine-readable output you can pipe to jq.

   praisonai usage --json

7. See per-tool reliability

   praisonai usage --by tool

   Reports calls, success rate, average latency, and the last error for each tool used.

Choose Your Grouping

Pick the --by value that matches the question you’re asking.

tool sorts by most-called first, so your busiest (or busiest-failing) tool rises to the top.

How It Works

praisonai usage reads the same session files that praisonai session list shows — nothing new is written, no external service is contacted.

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

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.

Options

Every option is optional — praisonai usage with no flags reports the last 30 days by day.

--by day sorts chronologically (ascending); --by model and --by project sort by tokens descending (highest spend first); --by tool sorts by call count descending, then alphabetically.

JSON output shape

--json emits a stable object you can pipe into dashboards or cron jobs.

praisonai usage --by day --days 30 --json

{
  "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": []
}

With --by tool, each row describes a tool instead of a spend bucket:

{
  "by": "tool",
  "days": 30,
  "project": null,
  "rows": [
    {
      "tool": "search",
      "calls": 3,
      "successes": 2,
      "errors": 1,
      "success_rate": 0.6667,
      "avg_ms": 200.0,
      "last_ms": 200.0,
      "last_error": "timeout"
    }
  ],
  "errors": []
}

Tool mode omits the top-level total_tokens / cost fields — it reports outcomes, not spend.

Empty output

• Table: No usage recorded yet
• JSON: {"rows": [], "total_tokens": 0, "cost": 0.0, ...}
• --by tool table: No tool usage recorded yet

Store errors

A missing or damaged store is non-fatal. Table mode prints Usage may be incomplete: <reason> 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, tool.

Common Patterns

Practical one-liners for everyday reviews.

# 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

# Spot flaky tools over the last week
praisonai usage --by tool --days 7

# Find the slowest tool across all history
praisonai usage --by tool --days 0 --json | jq '.rows | sort_by(-.avg_ms) | .[0]'

# Alert on tool failure rate in CI
praisonai usage --by tool --json | jq '.rows[] | select(.success_rate < 0.9)'

Grouping Modes

Per-Tool Reliability

praisonai usage --by tool reports per-tool call counts, success rate, average and last latency, and the last error — read from the local session store, same as every other grouping.

                                 Tool usage
┏━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Tool       ┃ Calls ┃ Success ┃ Avg ms ┃ Last ms ┃ Last error ┃
┡━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
│ search     │     3 │  66.7%  │   200  │   200   │ timeout    │
│ write_file │     1 │ 100.0%  │     5  │     5   │ -          │
└────────────┴───────┴─────────┴────────┴─────────┴────────────┘

Last ms and Last error are picked by when the tool itself last ran, not by when the session was last updated. If no tool calls are recorded, the command prints No tool usage recorded yet.

Best Practices

praisonai usage --project my-app --by model

praisonai usage --json | jq 'if .cost > 5 then error("over budget") else .cost end'

Related