Buying Credits with the Clay CLI

clay credits top-up starts a real purchase flow. This doc documents its schema from the CLI's own --help output; the purchase itself was not executed live, since it is a real charge to the workspace's billing method.

What you will build

An understanding of the once and auto top-up commands' input and output shapes, without completing a real transaction.

clay credits balance          (read-only, safe to run any time)
clay credits top-up once --credits <n>   (returns a checkout URL; not executed here)

AI Prompt

Document the Clay CLI's credit top-up commands from their own --help output, without
executing a real purchase.

Requirements:
- `clay credits top-up once --credits <n> [--open]` requires a minimum of 250 credits and
  returns { "url": string|null }, a checkout URL rather than a completed purchase.
- `clay credits top-up auto` manages recurring auto top-up settings; read its own --help
  for the exact subcommands before assuming its shape.
- auth_forbidden is returned when the calling key's holder lacks billing-management access
  to the workspace, separately from any credits-balance read access.
- Do not run `once` or complete an `auto` purchase against a real workspace's billing
  method as part of a demonstration. State plainly that this step was not executed live.

Prerequisites

• The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
• Billing-management access to the workspace, to avoid auth_forbidden on a real attempt

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. Read the current balance (safe, read-only)

clay credits balance

Real output:

{ "balance": 394273 }

2. The one-time top-up schema

clay credits top-up once --help

Real output (help text, not a purchase):

Usage: clay credits top-up once [options]

Options:
  --credits <n>  Number of credits to purchase (minimum 250).
  --open         Open the checkout URL in the default browser.

Output (success, exit 0):
  { "url": <string|null> }

Common errors:
  auth_forbidden (exit 3)    You lack billing-management access to this workspace.
  validation_error (exit 2)  --credits is missing, not a positive integer, or below 250.

This step was documented from --help only and was not executed against a real workspace, because it starts a real purchase flow.

Verify the result

clay credits top-up once --help

Expected: the options and output shape above, without running the command against a real workspace.

How it works

once does not itself charge anything; it returns a checkout URL (null in some failure paths) that completes the purchase in a browser, separately from the CLI call. That still makes the CLI call itself the first step of a real financial transaction, which is why this doc stops at documenting the schema rather than invoking it.

Common issues

--credits below the minimum

The command validates --credits against a floor of 250 before attempting to start a checkout session at all, returning a validation_error rather than a checkout URL for anything lower.

Billing access is separate from workspace access generally

An API key or session that can read credits balance is not guaranteed to have billing-management access. auth_forbidden here means the caller specifically lacks that narrower permission, not that authentication failed outright.

Next steps

• Measuring Real Signal Spend with the Clay CLI

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay credits top-up once --help"
  expected_result: "Documents --credits (minimum 250) and --open, returning { url } on success; the purchase itself was not executed."

Related Articles

• Measuring Real Signal Spend with the Clay CLI
• Qualifying Accounts by Funding Amount with TypeScript
• Can a command-line tool scaffold a new enrichment workflow from a reusable template?