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

# Cost

> Quick spend summary — total, top spenders, per-crew rollup, subscription usage — in one screen.

# Cost

`cmd/crewship/cmd_cost.go` is a high-density single-screen cost summary for the impatient. [`crewship paymaster ...`](/cli/paymaster) exposes the underlying rollups in full fidelity; `cost` is what you reach for when you just want to know "how much am I spending and on what?" without remembering which subcommand to run.

Composes three paymaster endpoints into one view:

* `GET /api/v1/paymaster/top-spenders` — N highest-spend scopes
* `GET /api/v1/paymaster/spend/by-crew` — per-crew rollup
* `GET /api/v1/paymaster/subscriptions` — subscription-plan usage (best-effort; not every workspace has plans)

All three are scoped to the same time range so rows line up.

## `crewship cost`

| Flag                 | Type   | Default | Effect                                                                                                     |
| -------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `--range <window>`   | string | `24h`   | Time window: `1h`, `24h`, `7d`, `30d`. Threaded into every underlying call.                                |
| `--limit <n>`        | int    | `5`     | Number of top spenders to print.                                                                           |
| `--watch <duration>` | string | `""`    | Auto-refresh every `<duration>` (e.g. `5s`, `1m`; min `1s`). Empty disables. Shared `addWatchFlag` helper. |

### Examples

```bash theme={null}
crewship cost
crewship cost --range 7d
crewship cost --range 30d --limit 10
crewship cost --format json     # full structured payload for scripts
crewship cost --watch 5s         # re-render every 5 seconds
```

### Output

```
Cost summary  range=24h  total=$3.4216  calls=421  crews=4
────────────────────────────────────────────────────────────────

Top spenders
   1. agent/agt_abc                            $  1.8421   142 calls
   2. crew/backend-team                        $  0.9100    87 calls
   ...

By crew
  backend-team                    $  1.8200    142 calls   54 211 tokens
  frontend-trio                   $  0.6100     94 calls   18 922 tokens

Subscription plans (no per-call $)
  team/anthropic  120 calls  41 222 tokens last=2026-05-19T13:00:00Z
```

Per-crew rows are sorted descending by `cost_usd` regardless of server return order, so the highest-spend crew is always at the top.

## `crewship cost forecast`

Project the cost of a future run **before** sending it. Two modes — pick by which flag you set:

```bash theme={null}
# Prompt-size projection (~4 chars/token heuristic, same rule as `crewship ask --estimate`)
crewship cost forecast --prompt "rewrite auth"
cat plan.md | crewship cost forecast --prompt @-
crewship cost forecast --prompt @plan.md

# History-based projection (averages the last 20 runs of <agent-slug>)
crewship cost forecast --from-history viktor
```

| Flag                          | Type   | Default | Effect                                                                                                                                                                  |
| ----------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--prompt <text\|@file\|@->`  | string |         | Prompt-mode source: literal text, `@path` to read a file, or `@-` for stdin.                                                                                            |
| `--from-history <agent-slug>` | string |         | History-mode source: averages the last 20 runs of the named agent.                                                                                                      |
| `--output-ratio <float>`      | float  | `2.0`   | Output tokens projected as this multiple of input tokens (prompt mode only). Most agent runs return less than the input on average — `2.0` is a generous safety margin. |

`--prompt` and `--from-history` are **mutually exclusive** and exactly one is required. Both modes print the same row layout (provider, input $, projected total $) so the output is directly comparable across modes.

History mode walks `/api/v1/runs?agent_id=<id>&limit=20`, sums `usage.input_tokens` / `usage.output_tokens` out of each run's `metadata`, and averages. Metadata blobs lacking the usage keys are skipped silently — runs from providers that don't report usage simply don't contribute to the average.

## See also

* [`crewship paymaster`](/cli/paymaster) — full-fidelity rollups (top, by-crew, by-agent, by-mission, subscriptions).
* [`crewship history`](/cli/history) — recent runs to correlate with cost spikes.