---
name: nixbuild-usage
description: |
  Report nixbuild.net account usage and cost posture — remaining free build
  time, billable CPU-seconds over a date range, build history (success/fail/
  discarded), output NAR size, and stored size. The account is metered, so
  this is the cost-visibility skill. Reads come from the HTTP API (nbapi tool,
  no PTY needed) plus the shell's `usage` command for the live free-time
  counter. Trigger on "nixbuild usage", "how much build time left", "nixbuild
  billing", "nixbuild storage", "nixbuild build history", "am I out of free
  build time", "nixbuild cost".
disable-model-invocation: false
allowed-tools: Bash, Read
---

# nixbuild-usage — metered account usage & cost

Owning agent: `nixbuild:ops`. nixbuild bills CPU-time beyond a monthly free
tier; this skill answers "where do I stand" without touching settings. Most of
it is the read-only HTTP API via **`nbapi`** (`${CLAUDE_PLUGIN_ROOT}/bin`), which
needs no PTY. The live free-time counter comes from the shell banner / `usage`.

## Quick posture

```bash
nbapi summary
```

Returns (example shape):

```json
{
  "build_count": 19, "running_build_count": 0,
  "discarded_build_count": 1, "failed_build_count": 1,
  "successful_build_count": 17,
  "total_cpu_seconds": 27401, "billable_cpu_seconds": 20963,
  "total_duration_seconds": 2708.06, "wall_time_seconds": 48398.44,
  "total_output_nar_size_kilobytes": 786691
}
```

Key fields: `billable_cpu_seconds` (what you pay for), `successful/failed/
discarded_build_count`, `total_output_nar_size_kilobytes`.

## Remaining free build time (live)

The free-tier counter is only in the shell, not the HTTP API:

```bash
nbshell 'usage'
```

The shell login banner also prints it, e.g. `Free build time left: 25:00:00
(hh:mm:ss)` — it resets at the start of each month. When spent, the banner
reads `You have no free build time left` and further builds are billed.

## Billable CPU over a date range

```bash
nbapi usage --from 2026-06-01 --to 2026-06-30
```

## Recent build history

```bash
nbapi builds --limit 20
```

Each entry carries id, status, drv path, timing — useful to spot a runaway or
repeatedly-failing build burning CPU. For one build's detail (including
`status_message`): `nbapi build <id>`. For the full build log:
`nbshell 'builds log <id>'`. For a shareable web link: `nbapi raw /builds/<id>/url`.

## Stored size

`Storage used:` appears in the shell banner (`nbshell 'usage'`), and
`total_output_nar_size_kilobytes` in `nbapi summary` approximates output volume.

## Reporting

Lead with the two numbers that matter: **free time left** and **billable
CPU-seconds** (this month). Add fail/discard counts only if non-trivial (a high
`failed`/`discarded` ratio means wasted spend — flag it). Convert CPU-seconds to
hours for readability (`/3600`). Keep it to a few lines unless asked for the
full history.

## Token

`nbapi` reads the bearer token from `$NIXBUILD_API_TOKEN`, else `pass show
infra/nixbuild/api-token` (override the entry with
`$NIXBUILD_API_TOKEN_PASS_ENTRY`). The read-only API needs only the `:read`
scopes; a broad token works but is more than required.