# Billing (/sling-cli/commands/billing)



Two read-only commands. Plan and payment changes stay in the dashboard; `sling` never mutates billing state.

## `sling bill`

```text
sling bill [--org <slug>] [--month <YYYY-MM>] [--json | --agent]
```

A budget snapshot for the current open billing period: runner minutes, cost, credits, amount due, per-runner-label line items, and a run-rate month-end projection.

| Flag                | Meaning                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------- |
| `--org`             | Scope. Defaults to your default org.                                                    |
| `--month <YYYY-MM>` | A **past** month, resolving to its finalized invoice. Omit for the current open period. |
| `--json`, `--agent` | Machine mode — the `/api/bill` envelope on stdout, wrapped with a `local` block.        |

```console
$ sling bill --org partcleda
StarSling bill — current period
Billing period · 2026-07-02 → 2026-08-02
Invoice: pending (issued when the period closes)

Runner minutes        45390.0
Amount                $396.91
Projected month-end   $848.43

RUNNER LABEL                          TIME          COST

starsling-ubuntu-24.04        41166.0 min       $329.33
starsling-ubuntu-24.04-8       4224.0 min        $67.58

Plan & payment changes live in the dashboard — this command is read-only.
```

<Callout type="warn">
  Other window flags — `--window`, `--from`, `--to` — are **rejected** here. A bill covers a fixed billing period, so an arbitrary range is meaningless. Use [`sling usage`](/sling-cli/commands/analyze#sling-usage) for arbitrary ranges.
</Callout>

### A closed month

Passing `--month` for a closed period resolves to its finalized invoice: a real invoice id, a status, and `Credit` / `Amount due` in place of the run-rate projection.

```console
$ sling bill --month 2026-06 --org partcleda
StarSling bill — invoice
Billing period · 2026-06-02 → 2026-07-02
Invoice: in_1ToapkFSjWlUgKNBIKavWGIJ

Runner minutes        120978.0
Amount                $1055.56
Credit                −$527.78
Amount due            $0.00
Status                paid
```

### Response fields

| Field                                                 | Meaning                                                                                        |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `invoice_id`                                          | Omitted for the open period; a Stripe invoice id for a finalized month.                        |
| `status`                                              | `open` for the current period; the Stripe status (`paid`, `open`, …) for a finalized month.    |
| `amount_usd`                                          | Gross billed — the Stripe subtotal for an invoice, in-house run-rate cost for the open period. |
| `credits_usd`                                         | All reductions off the gross: a partner discount and/or the free grant.                        |
| `amount_due_usd`                                      | Still outstanding. `$0` once an invoice is paid.                                               |
| `free_credit_total_usd` / `free_credit_remaining_usd` | Free orgs only — the one-time lifetime grant. Omitted otherwise.                               |
| `line_items`                                          | Per-runner-label minutes and cost.                                                             |
| `projected_month_end_usd`                             | Run-rate projection for the open period; the finalized net billed for an invoice.              |

A field the org does not have — a paid org's grant fields — is omitted rather than erroring. Calls [`GET /api/bill`](/api/bill/get-bill).

## `sling bill history`

```text
sling bill history [--org <slug>] [-n <count>] [--after <invoice_id>] [--json | --agent]
```

Prior **finalized** invoices, newest first. Each carries Stripe's authoritative id, status, and amount, joined with per-label usage.

| Flag                   | Meaning                                                               |
| ---------------------- | --------------------------------------------------------------------- |
| `-n`, `--limit`        | How many invoices — 1 to 100, default 6.                              |
| `--after <invoice_id>` | Cursor. Pages to invoices older than the given id; follow `has_more`. |
| `--json`, `--agent`    | Machine mode — `{ invoices, has_more }` on stdout.                    |

```console
$ sling bill history --org partcleda
StarSling bill — prior invoices (newest first)

INVOICE                      PERIOD                  STATUS   RUNNER MIN     AMOUNT     CREDIT       DUE
in_1ToapkFSjWlUgKNBIKavWGIJ  2026-06-02 → 2026-07-02 paid       120978.0   $1055.56   −$527.78     $0.00
  RUNNER LABEL                     MINUTES          COST
  starsling-ubuntu-24.04          112049.0       $896.39
  starsling-ubuntu-24.04-8          8775.0       $140.40

AMOUNT is Stripe's gross (before −CREDIT); DUE is what's still outstanding ($0 once paid).
```

Note that `--after` takes an **invoice id**, not the opaque cursor the listing endpoints use. Calls [`GET /api/bill/history`](/api/bill/get-bill-history).

## Exit codes

Both commands: `0` ok · `2` usage error · `4` not signed in · `5` control-plane failure. The human view is chrome and goes to stderr, so `sling bill --json | jq` is safe to pipe unconditionally. See [Pricing](/pricing) for how the rates are set.