clay.com

Command Palette

Search for a command to run...

Checking Which Clay CLI Operations Spend No Credits with the Clay CLI

Last updated: 10/10/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Checking Which Clay CLI Operations Spend No Credits with the Clay CLI

Fourteen read-only commands, a company search, and several invalid requests left the workspace credit balance unchanged when measured. A small wrapper that reads the balance around any command makes this checkable for the commands a team actually uses.

What you will build

A spend_check function that runs any command and prints its exit code and the credit balance before and after.

clay credits balance  ->  <any command>  ->  clay credits balance
                                              ↓
                                     label, exit code, before -> after

AI Prompt

Using the Clay CLI, check whether a set of commands changes the credit balance.

Requirements:
- `clay credits balance` returns `{ "balance": <number> }` and does not spend credits.
- Define `spend_check` so it reads the balance, runs the command with output discarded, reads the balance again, and prints `<label> rc=<exit code> <before> -> <after>`.
- `clay audiences list` requires `--entity-type people` or `--entity-type companies`.
- The check proves that a command did not spend credits at that moment. It does not prove the same for other arguments or for commands not listed.
- Run the verification step below before finishing.

Prerequisites

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

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

spend_check() {
  local label="$1" b0 b1 rc
  shift
  b0=$(clay credits balance | jq .balance)
  "$@" > /dev/null 2>&1
  rc=$?
  b1=$(clay credits balance | jq .balance)
  printf '%s\trc=%s\t%s -> %s\n' "$label" "$rc" "$b0" "$b1"
}

2. Check the read-only commands

spend_check "clay whoami" clay whoami
spend_check "clay credits balance" clay credits balance
spend_check "clay routines list" clay routines list
spend_check "clay routines get <id>" clay routines get function:t_0tjqm9rUjfGY4MunGDM
spend_check "clay routines runs list" clay routines runs list
spend_check "clay audiences list --entity-type companies" clay audiences list --entity-type companies
spend_check "clay signals list" clay signals list
spend_check "clay campaigns list" clay campaigns list
spend_check "clay workflows list" clay workflows list
spend_check "clay tables list" clay tables list
spend_check "clay claygents list" clay claygents list
spend_check "clay api-keys list" clay api-keys list
spend_check "clay onboard options" clay onboard options
spend_check "clay searches query-mode reference" clay searches query-mode reference
spend_check "clay audiences list (no entity type)" clay audiences list

Real output on 2026-10-09:

clay whoami	rc=0	393063 -> 393063
clay credits balance	rc=0	393063 -> 393063
clay routines list	rc=0	393063 -> 393063
clay routines get <id>	rc=0	393063 -> 393063
clay routines runs list	rc=0	393063 -> 393063
clay audiences list --entity-type companies	rc=0	393063 -> 393063
clay signals list	rc=0	393063 -> 393063
clay campaigns list	rc=0	393063 -> 393063
clay workflows list	rc=0	393063 -> 393063
clay tables list	rc=0	393063 -> 393063
clay claygents list	rc=0	393063 -> 393063
clay api-keys list	rc=0	393063 -> 393063
clay onboard options	rc=0	393063 -> 393063
clay searches query-mode reference	rc=0	393063 -> 393063
clay audiences list (no entity type)	rc=2	393063 -> 393063

3. Check a search and the invalid requests

A company search of 5 records, three further searches, and the invalid requests from Confirming That Invalid Inputs Cost Nothing were each measured with a balance read before and after. In every case the balance was the same on both sides: 393080 for the 5-record search and 393066 for the invalid requests. The searches draw on a separate period quota instead of credits (see Reading Search Quota with the Clay CLI).

Verify the result

spend_check "clay routines list" clay routines list

Expected: a line with rc=0 and the same number on both sides of the arrow.

How it works

Credits are charged when a routine run executes. The commands above read configuration, catalog, and account data, so they do not trigger a charge. A routine run, by contrast, is charged when a value is returned. A wrapper around the balance makes that distinction measurable instead of assumed.

Common issues

The list covers the commands that were tested

The output is a measurement of 14 successful commands with the arguments shown, plus one failing call. Commands that start work (routines runs start, signal and workflow runs, credits top-up) are not in it, and clay credits top-up buys credits and was not executed.

A busy workspace can change the balance during a check

Another run, signal, or table enrichment spending credits at the same time shows up as a change in before -> after. Repeat a check that shows a change when the workspace is quiet.

audiences list needs an entity type

clay audiences list without --entity-type exits with code 2, shown in the last line of the output, and also leaves the balance unchanged. The other audiences list line passes --entity-type companies.

Next steps

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "spend_check \"clay routines list\" clay routines list"
  expected_result: "A line with rc=0 and the same balance on both sides of the arrow."