> ## 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.

# Paymaster Commands

> Cost and budget rollups across the workspace.

# crewship paymaster

View LLM spend rolled up by crew, agent, or mission. Reads from the `cost_ledger` table populated by the [Paymaster middleware](/guides/paymaster).

```bash theme={null}
crewship paymaster <subcommand> [flags]
```

## Subcommands

| Command                  | Description                                             |
| ------------------------ | ------------------------------------------------------- |
| `by-crew`                | Spend per crew in the workspace.                        |
| `by-agent <crew>`        | Spend per agent inside a specific crew.                 |
| `by-mission <missionId>` | Spend rolled up for a single mission.                   |
| `top`                    | Highest-cost scopes in the window.                      |
| `subscriptions`          | Subscription-plan usage rollup (flat-rate credentials). |

***

## `crewship paymaster by-crew`

```bash theme={null}
crewship paymaster by-crew
crewship paymaster by-crew --range 24h
```

| Flag      | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `--range` | `string` | `7d`    | Time window: `1h`, `24h`, `7d`, or `30d`. |

Sample output:

```
Crew                            Cost (USD)   Calls       Tokens
────────────────────────────────────────────────────────────────
backend-team                    $ 14.3210      132      1,482,341
marketing                       $  3.9802       28        281,004
```

***

## `crewship paymaster by-agent <crew>`

```bash theme={null}
crewship paymaster by-agent backend-team
crewship paymaster by-agent backend-team --range 24h
```

| Flag      | Type     | Default | Description  |
| --------- | -------- | ------- | ------------ |
| `--range` | `string` | `7d`    | Time window. |

Takes a crew slug or ID as positional arg. Output columns: Agent, Cost (USD), Calls, Tokens.

***

## `crewship paymaster by-mission <missionId>`

Return the total cost ledger for a single mission (cost, call count, input/output tokens). Mission is workspace-scoped; foreign mission IDs return 404. There is no `--range` flag here — the server returns the mission's full cost history.

```bash theme={null}
crewship paymaster by-mission mis_abc123
crewship paymaster by-mission mis_abc123 --format json | jq .row.cost_usd
```

***

## `crewship paymaster top`

```bash theme={null}
crewship paymaster top --limit 5 --range 30d
```

| Flag      | Type     | Default | Description             |
| --------- | -------- | ------- | ----------------------- |
| `--limit` | `int`    | `10`    | Top N spenders (1-100). |
| `--range` | `string` | `7d`    | Time window.            |

Sample output:

```
 1. crew/backend-team                           $ 14.3210   132 calls
 2. crew/marketing                              $  3.9802    28 calls
 3. agent/viktor                                $  2.1045    18 calls
```

Scope format: `<scope_kind>/<scope_id>` (one of `workspace`, `crew`, `mission`, `agent`).

***

## `crewship paymaster subscriptions`

Show flat-rate subscription usage — the API counterpart to the "Subscription plans" panel on the Paymaster dashboard. No `$`-figures because flat-rate cost is always `$0` by construction; the row shape is plan + provider + call\_count + token totals + last\_used.

```bash theme={null}
crewship paymaster subscriptions
crewship paymaster subscriptions --range 30d
crewship paymaster subscriptions --format json | jq '.[].call_count'
```

| Flag      | Type     | Default | Description                                             |
| --------- | -------- | ------- | ------------------------------------------------------- |
| `--range` | `string` | `7d`    | Time window: `1h`, `24h`, `7d`, or `30d`.               |
| `--since` | `string` |         | RFC3339 start cutoff (overrides `--range` if both set). |
| `--until` | `string` |         | RFC3339 end cutoff.                                     |

***

## Global output

`--format json|yaml` works for every subcommand and emits the raw rollup structs from the API.

## Known limitation

<Warning>
  Paymaster metering **only captures calls that flow through `internal/llm`**
  (Keeper, summaries, consolidation, quartermaster). Calls made by the
  agent's own CLI adapter (`claude`, `gemini`) talking directly to the
  provider API **are not recorded in `cost_ledger`**. See the
  [Paymaster guide](/guides/paymaster) for details.

  Consequence: the numbers here are accurate for server-side LLM activity;
  agent-driven spend is visible only on the provider's dashboard. Use
  workspace-wide budgets as the authoritative cap until the proxy rework
  lands.
</Warning>

## Related

* [Paymaster guide](/guides/paymaster).
* [Paymaster API](/api-reference/paymaster).