> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# dome usage

> Show LLM token usage and estimated cost for the active workspace

Print LLM token consumption and a per-class cost estimate for the active workspace. Use it to spot-check spend, build budget alerts in scripts, or confirm token attribution matches what the dashboard and `dome_usage` MCP tool show.

<Note>
  The estimated cost is a blended cross-model rate intended for trend-watching, not a billable figure. Refer to [Token Usage and Cost](/operate/observe#token-usage-and-cost) for the full token-class breakdown and pricing model.
</Note>

## Usage

`dome usage`

Reads `GET /api/v1/metrics/summary` for the active workspace over the last 24 hours and renders the totals.

| Flag     | Type | Description                  |
| -------- | ---- | ---------------------------- |
| `--json` | bool | Output as JSON for scripting |

**Permission:** workspace `audit.view`

**Prerequisites:** active workspace selected (`dome context use <workspace>` or `dome workspace use <id>`).

```bash theme={"system"}
dome usage
```

Output (table):

```
LLM token usage (last 24h)
  Input tokens         412000
  Cache read tokens    1820000
  Cache write tokens   88000
  Output tokens        64000
  Reasoning tokens     12000
  Total tokens         2396000
  Estimated cost       $3.4521 (per-class estimate, not billable)
```

Output (`--json`):

```json theme={"system"}
{
  "llm_input_tokens": 412000,
  "llm_cache_read_tokens": 1820000,
  "llm_cache_write_tokens": 88000,
  "llm_output_tokens": 64000,
  "llm_reasoning_tokens": 12000,
  "llm_total_tokens": 2396000,
  "estimated_cost_usd": 3.4521
}
```

Pipe into `jq` to build budget guards:

```bash theme={"system"}
# Fail if estimated 24h spend crosses $10
cost=$(dome usage --json | jq '.estimated_cost_usd')
awk "BEGIN { exit !($cost > 10) }" && echo "over budget" >&2
```

For per-agent, per-key, per-identity, or per-model attribution, see the [REST query surface](/operate/observe#token-usage-and-cost) — the dashboard and the [`dome_usage`](/reference/mcp/audit#audit-usage) MCP tool consume the same endpoints.