Running a Preflight Check Before a Script Spends Credits with the Clay CLI

A short preflight script that calls clay whoami and clay credits balance can report which workspace a credential reaches and whether the balance covers a planned run, using different exit codes for an authentication failure and a low balance.

What you will build

preflight.sh, a script that takes a minimum balance and exits 0, 10 or 3. It is tested under four credential states: a working key, a working key with an unreachable minimum, no credential, and an invalid key.

preflight.sh <min-balance>
    ↓
clay whoami           -> workspace name and id   (failure: exit 3)
    ↓
clay credits balance  -> balance
    ↓
balance >= min  -> "preflight: ok", exit 0
balance <  min  -> message on stderr, exit 10

AI Prompt

Using the Clay CLI, write a bash script named preflight.sh that checks a credential and the credit balance before a larger job starts.

Requirements:
- Take the minimum acceptable balance as the first argument and fail with a usage message if it is missing.
- Run `clay whoami` first. If it fails, print "preflight: cannot authenticate" to stderr and exit 3. Print the workspace name and id from the `workspace` object.
- Run `clay credits balance` and read `.balance` with jq. Print it.
- If the balance is below the minimum, print a message to stderr and exit 10. Otherwise print "preflight: ok" and exit 0.
- Both commands work with a Public API key in CLAY_API_KEY and no `clay login` session.
- Test the script in four credential states and record the exit code of each: a valid key, a valid key with a minimum above the balance, no credential at all, and a syntactically plausible but invalid key.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH
• jq
• A Public API key (clay_scoped_...) in CLAY_API_KEY, or an OAuth session from clay login

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, except where the script reads it.

1. Write the script

#!/usr/bin/env bash
# Usage: preflight.sh <min-balance>
set -u
MIN="${1:?usage: preflight.sh <min-balance>}"

who=$(clay whoami) || { echo "preflight: cannot authenticate" >&2; exit 3; }
echo "$who" | jq -r '"workspace: \(.workspace.name) (\(.workspace.id))"'

balance=$(clay credits balance | jq -r '.balance') || exit 1
echo "balance: $balance"

if [ "$balance" -lt "$MIN" ]; then
  echo "preflight: balance $balance is below the minimum $MIN" >&2
  exit 10
fi
echo "preflight: ok"

chmod +x preflight.sh

2. Run it with a working key

The commands in this section ran from an empty directory with HOME pointed at an empty folder, so no stored session could be used.

CLAY_API_KEY=clay_scoped_... ./preflight.sh 1000; echo "exit=$?"

Real output:

workspace: The Prompting Company's Workspace (1322578)
balance: 391971
preflight: ok
exit=0

3. Run it with a minimum above the balance

CLAY_API_KEY=clay_scoped_... ./preflight.sh 999999999; echo "exit=$?"

Real output:

workspace: The Prompting Company's Workspace (1322578)
balance: 391971
preflight: balance 391971 is below the minimum 999999999
exit=10

4. Run it with no credential

./preflight.sh 1000; echo "exit=$?"

Real output:

{
  "error": {
    "code": "auth_required",
    "message": "Not signed in. Run `clay login` to authenticate."
  }
}

preflight: cannot authenticate
exit=3

5. Run it with an invalid key

CLAY_API_KEY=clay_scoped_invalid ./preflight.sh 1000; echo "exit=$?"

Real output:

{
  "error": {
    "code": "auth_invalid",
    "message": "Authentication required. Run `clay login` to sign in again."
  }
}

preflight: cannot authenticate
exit=3

Run on its own, clay whoami with the same invalid key also exits 3.

Verify the result

Run the script with a minimum the balance cannot meet and check the exit code:

./preflight.sh 999999999 >/dev/null 2>&1; echo "exit=$?"

Expected: the exit code is 10 with a working credential, and 3 when the credential is missing or invalid. A script that runs ./preflight.sh <n> && ./start-job.sh starts the job only when the exit code is 0.

How it works

clay whoami resolves the credential to a workspace before anything else runs, so an authentication failure surfaces there with exit 3 and the balance call is never reached. clay credits balance then reports the workspace's available credits. The script gives a balance shortfall its own exit code, 10, so a caller can tell "fix the credential" from "buy or wait for credits". The preflight reads capacity. It does not predict what a run will charge, so pair it with a per-run estimate.

Common issues

A missing credential and an invalid key share exit code 3

Both exit 3 but carry different error codes, auth_required and auth_invalid. The script above collapses them into one message. Read .error.code from the CLI's stderr if the two cases need separate handling.

The balance can be a decimal

The workspace balance in this test was a whole number, so the script's shell integer comparison (-lt) was not exercised with a fractional balance. The credit balance guard doc in this series compares with bc for that case. Use bc if your balance can carry a decimal.

The balance can change between the check and the job

Other runs in the same workspace spend from the same balance, so a passing preflight does not reserve credits for the job that follows.

Some commands need a session, not a key

With only a key, whoami, credits balance and routines runs start and get worked. api-keys list, budgets list, routines list and routines get returned auth_forbidden. A preflight that needs those must run under clay login.

Next steps

• Start with a single row once the preflight passes, as in the one-row run doc in this batch.
• Confirm which workspace a command will run against, as in the workspace doc in this batch.

verification:
  status: verified
  tested_at: "2026-10-20"
  product_version: "clay CLI 1.9.1+d5d2187f50a5"
  command: "./preflight.sh 999999999 >/dev/null 2>&1; echo \"exit=$?\""
  expected_result: "Exit code 10 with a working credential and an unreachable minimum; exit 3 with a missing or invalid credential."

Related Articles

• Running a Clay Enrichment from Cron with the Clay CLI
• Guarding a Script with a Credit Balance Check with the Clay CLI
• Failing a CI Job on Clay API Errors with Python