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

# orca billing

> Show the tenant credit wallet, and view or set the monthly spend cap.

> **Last updated: 2026-09-06**

`orca billing` is the CLI view of [billing](/concepts/billing): the prepaid credit wallet that runs draw down, and the monthly spend cap that blocks new runs once it is reached. The wallet is read-only from the CLI; credits are added in the dashboard. Only the monthly cap is self-serve; the daily window is an operator guard and cannot be set here.

Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). `orca billing cap set` prompts for confirmation in a terminal; in a script `--yes` is required or the command refuses (exit code 2).

## orca billing wallet

```bash theme={"dark"}
orca billing wallet
```

Shows the tenant credit balance from `GET /api/billing/wallet`. `configured` is `false` when the tenant has never been granted credits, in which case the balance stays at zero and the terminal view says `no credits yet`. When credits are configured and the balance is at or below zero the balance is highlighted as exhausted.

```bash theme={"dark"}
orca billing wallet --json
```

With `--json` the wallet object is printed: `configured`, `balanceMicroUSD`, `balanceUSD`, and `packs` (the purchasable top-up sizes, each `{ cents, usd }`). Plain (piped) output is one tab-separated `key`, `value` row each for `configured`, `balanceUSD`, `balanceMicroUSD`, and `packs` (pack sizes in cents, comma-separated, or `-`).

## orca billing cap

```bash theme={"dark"}
orca billing cap
```

Shows the monthly spend cap and accrued spend from `GET /api/spend-cap`. The terminal view prints the monthly cap, spent, remaining, the reset date, and the billing email, with the subtitle `custom monthly limit` when the tenant set the cap and `system default` otherwise. Spent and remaining are highlighted when the cap is exhausted.

```bash theme={"dark"}
orca billing cap --json
```

With `--json` the full spend-cap response is printed: `enabled`, `month`, `day`, and `billing_email`, where each window carries `limit_usd_cents`, `limit_usd`, `spent_usd_cents`, `spent_usd`, `remaining_usd_cents`, `user_set`, and `resets_at`. Plain (piped) output is one tab-separated `key`, `value` row each for the monthly `limit_usd_cents`, `spent_usd_cents`, `remaining_usd_cents`, `user_set`, `resets_at`, and `billing_email` (or `-`).

## orca billing cap set

```bash theme={"dark"}
orca billing cap set <amount> [--email <address>] [--yes]
```

Sets the monthly spend cap with `PUT /api/spend-cap`. `<amount>` is a dollar figure: `10`, `10.5`, `10.50`, `$10`, or `1,000` (a leading `$` and thousands separators are stripped; at most two decimal places; negative amounts are rejected). Pass the literal `default` (or `none` or `clear`, case-insensitive) to clear the tenant override and revert to the system default. The amount is validated before any network call, so a bad value exits 2 with no side effects.

Before writing, the command reads the current cap and warns on stderr when the new cap is below the spend already accrued this month, because the platform gates run creation on the cap fail-closed and new runs would be blocked until the window resets. A failed read does not block the set.

| Flag                | Type    | Default   | Description                                                             |
| ------------------- | ------- | --------- | ----------------------------------------------------------------------- |
| `--email <address>` | string  | unchanged | Also set the tenant billing email (`billing_email`) in the same request |
| `--yes`             | boolean | `false`   | Skip the confirmation prompt                                            |

```bash theme={"dark"}
orca billing cap set 250 --email finance@example.com --yes
orca billing cap set default --yes --json
```

With `--json` the updated spend-cap response is printed (the same shape as `orca billing cap --json`).

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>