libra usage

Report and prune AI provider/model and agent usage aggregates for the current repository.

Synopsis

libra usage report [OPTIONS]
libra usage prune [--retention-days <days>]

Description

libra usage reads usage rows recorded by Libra's AI provider runtime and aggregates them by provider/model, agent, or agent/provider/model. Reports can be filtered by time range, session id, thread id, and whether failed provider requests should be included. When a provider reports an exact cost_usd, Libra stores and displays that value. Otherwise it estimates cost_estimate_micro_dollars from the built-in model capability pricing table or a repository override in .libra/config.toml.

Subcommands

Report Options

Prune Options

Human Output

Human reports print one tab-separated row per selected grouping.

Default provider/model grouping:

<provider>	<model>	requests=<n>	failed=<n>	tokens=<n>	cached=<n>	reasoning=<n>	tool_calls=<n>	wall_ms=<n> [ $<actual>| ~$<estimate>]

Agent grouping:

<agent_name>	requests=<n>	failed=<n>	tokens=<n>	cached=<n>	reasoning=<n>	tool_calls=<n>	wall_ms=<n> [ $<actual>| ~$<estimate>]

Agent/provider/model grouping:

<agent_name>	<provider>	<model>	requests=<n>	failed=<n>	tokens=<n>	cached=<n>	reasoning=<n>	tool_calls=<n>	wall_ms=<n> [ $<actual>| ~$<estimate>]

CSV mode prints a header row followed by comma-separated rows suitable for spreadsheet import. The CSV leading columns match the selected grouping, and the metric columns include both cost_usd and cost_estimate_micro_dollars; estimated human output is prefixed with ~$.

Pricing Overrides

Repository-local usage settings live in .libra/config.toml. Price overrides are keyed by provider and model. Values are micro-dollars per million tokens:

[usage]
retention_days = 90

[usage.pricing.openai."gpt-4o-mini"]
input_micro_dollars_per_mtok = 150000
output_micro_dollars_per_mtok = 600000
cached_micro_dollars_per_mtok = 75000
reasoning_micro_dollars_per_mtok = 600000

If the config is missing or a provider/model has no built-in or overridden price, the usage row is still written and cost_estimate_micro_dollars remains empty.

libra usage prune uses [usage].retention_days when --retention-days is not passed. The flag always wins over the project config.

JSON Output

report uses the usage.report envelope:

{
  "ok": true,
  "command": "usage.report",
  "data": {
    "by": "model",
    "filter": {
      "since": null,
      "until": null,
      "session": null,
      "thread": null,
      "include_failed": false
    },
    "rows": []
  }
}

prune uses usage.prune and reports the retention window, cutoff timestamp, and deleted row count.

Examples

# Per-model totals across all recorded rows
libra usage report

# Per-model totals for the last 24 hours
libra usage report --since 24h

# Per-agent totals
libra usage report --by agent

# Per-agent provider/model breakdown
libra usage report --by agent-provider-model

# Include failed requests in counts and wall-clock totals
libra usage report --since 7d --include-failed

# Restrict the report to a single session
libra usage report --session <session-id>

# Restrict the report to a single canonical thread
libra usage report --thread <thread-uuid>

# CSV table for downstream tooling (spreadsheets, BI dashboards)
libra usage report --format csv

# Structured JSON envelope for agents
libra usage --json report --since 7d

# Use the configured retention window (.libra/libra.db config `[usage].retention_days`)
libra usage prune

# Delete rows older than 30 days
libra usage prune --retention-days 30

The same banner is rendered by libra usage --help so the doc and the CLI surface stay in sync (cross-cutting --help EXAMPLES rollout, see docs/development/commands/_general.md item B).

Notes

• The command requires a Libra repository because usage rows live in .libra/libra.db.
• Relative time filters are evaluated at command runtime and normalized to RFC3339 before querying.
• Retention windows must be greater than 0; invalid config fails closed before deleting rows.