Guarding a Script with a Credit Balance Check with the Clay CLI

A shell function that reads clay credits balance and returns a non-zero exit code when the balance is below a required amount lets a script stop before it starts a run it cannot afford.

What you will build

A require_credits function, tested in the passing case and in two blocking cases.

require_credits <needed>
    ↓
clay credits balance  ->  balance
    ↓
balance >= needed  ->  "ok", exit 0
balance <  needed  ->  "blocked" on stderr, exit 1

AI Prompt

Using the Clay CLI, write a shell function that blocks a script when the credit balance is too low.

Requirements:
- `clay credits balance` returns `{ "balance": <number> }`. The balance can be a decimal.
- Compare with `bc` so a fractional balance or requirement is handled. Shell integer tests do not accept decimals.
- On success print `ok: need <n> credits, have <n>` and return 0. On failure print `blocked: need <n> credits, have <n>` to stderr and return 1.
- A balance is available capacity, not an estimate of what a particular run charges. Pair this check with a cost estimate for the run.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH, authenticated via clay login
• jq and bc

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Define the function

require_credits() {
  local need="$1" have
  have=$(clay credits balance | jq .balance)
  if [ "$(echo "$have < $need" | bc)" = 1 ]; then
    echo "blocked: need $need credits, have $have" >&2
    return 1
  fi
  echo "ok: need $need credits, have $have"
}

2. Test it

require_credits 100; echo "exit=$?"
require_credits 999999999; echo "exit=$?"
require_credits 393066.5; echo "exit=$?"

Real output, with the workspace balance at 393066:

ok: need 100 credits, have 393066
exit=0
blocked: need 999999999 credits, have 393066
exit=1
blocked: need 393066.5 credits, have 393066
exit=1

The third call shows a requirement half a credit above the balance being blocked.

3. Use it in front of a run

require_credits 3 || exit 1
clay routines runs start function:t_0tjqm9rUjfGY4MunGDM --bulk rows.jsonl

The || form stops the script when the function returns 1, before the start command runs.

Verify the result

require_credits 999999999; echo "exit=$?"

Expected: a blocked: line on stderr and exit=1.

How it works

clay credits balance reports the workspace's remaining credits. The function compares that number with the amount the script needs and returns an exit code, which shell control flow can act on. bc handles decimal values, which matters because routine estimates such as 3.3 or 18.2 per run are decimals.

Common issues

A balance check does not reserve credits

Two scripts can both pass the check and then spend more than the balance in total. The check protects a single script on a quiet workspace.

Use a cost estimate to choose the amount

Passing a guessed number defeats the purpose. Estimating a Batch Cost Before Running It shows how to compute the amount from the routine's estimatedCreditCost and the number of rows.

Integer comparison fails on decimals

[ "$have" -lt 100 ] with have=393066.5 fails with integer expression expected: 393066.5 and exit code 2. The bc comparison above does not.

Next steps

• Estimating a Batch Cost Before Running It with the Clay CLI
• Running a Bulk Routine Batch from a JSONL File with the Clay CLI

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "require_credits 999999999; echo \"exit=$?\""
  expected_result: "A blocked line on stderr and exit=1."