clay.com

Command Palette

Search for a command to run...

Checking Credit Budgets and Approval Requests with the Clay CLI

Last updated: 10/20/2026

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

Checking Credit Budgets and Approval Requests with the Clay CLI

clay budgets list returns the credit budgets a user can assign to resources, and clay approvals reads and decides approval requests, but a workspace with no budgets and no pending requests returns an empty list and not_found, so neither command can be demonstrated end to end there.

What you will build

A read-only check of both command groups that records what a workspace with neither feature in use returns, and lists which steps were not run.

clay budgets list                  -> { "data": [] }
clay approvals get <id>            -> not_found, exit 6
clay approvals approve <id>        -> not_found, exit 6
clay approvals deny <id>           -> not_found, exit 6
(key-only) clay budgets list       -> auth_forbidden, exit 3

AI Prompt

Using the Clay CLI, check whether a workspace has credit budgets or approval requests, and report the result without inventing data.

Requirements:
- `clay budgets list` returns `{ "data": [{ "id", "name", "currentBalance", "creditLimit", "resetPeriod", "nextResetAt" }] }`. An empty `data` array means the user has no accessible budgets. It exits 3 with `auth_forbidden` when credit budgets are not enabled or the credential cannot read them.
- `clay approvals get|approve|deny <requestId>` take an id like `aar_abc123`. An unknown id returns `not_found` with exit 6. `approve` runs the requested action, so never call it on an id you did not create or review.
- Do not create budgets or approval requests. Neither is creatable from the CLI commands listed here, so state plainly which steps were not run.
- `budgets list` needs an OAuth session. Test it once with only a Public API key and record the exit code.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH and a session from clay login
  • jq for the verification command

Note: The workspace: { id, name } object that each real response carries is left out of the samples below.

1. List budgets

clay budgets list

Real output:

{
  "data": []
}

The workspace in this test had no budgets that the signed-in user could assign.

2. Read the budget schema from help

clay budgets list --help

The help text documents each returned budget as id, name, currentBalance (number or null), creditLimit (number or null), resetPeriod (string) and nextResetAt (string or null). Because step 1 returned no entries, this doc could not show a populated budget, and these field types come from the help text, not from a response.

3. Read an approval request that does not exist

clay approvals get nonexistent-id; echo "exit=$?"

Real output:

{
  "error": {
    "code": "not_found",
    "message": "Action approval request not found"
  }
}

exit=6

4. Approve and deny an id that does not exist

clay approvals approve nonexistent-id; echo "exit=$?"
clay approvals deny nonexistent-id; echo "exit=$?"

Both returned the same error as step 3:

{
  "error": {
    "code": "not_found",
    "message": "Action approval request not found"
  }
}

exit=6
exit=6

Neither command had any effect, since there was no request to decide.

5. Read budgets with only an API key

Run from an empty folder, with HOME set to another empty folder and CLAY_API_KEY exported:

clay budgets list; echo "exit=$?"

Real output:

{
  "error": {
    "code": "auth_forbidden",
    "message": "Insufficient permissions. Run `clay login` to sign in again."
  }
}

exit=3

Verify the result

clay budgets list | jq '.data | length'

Expected: a number. In the test workspace it was 0. A script can branch on it: with a positive count, read currentBalance and creditLimit before a run; with 0, fall back to the workspace balance from clay credits balance.

How it works

budgets list is a read-only listing scoped to what the signed-in user can assign, so an empty array describes that user's access, not necessarily the absence of budgets in the workspace. The approvals group addresses requests by id. get reads one, and approve and deny record a decision. The help text says approve runs the requested action and that a request with an existing decision returns conflict with exit 1.

Common issues

An empty data array does not distinguish "none exist" from "none visible to you"

The command's help states that only budgets the current user can access and assign are returned. Ask a workspace admin before concluding that no budgets are configured.

Approvals have no list command here

The approvals group has get, approve and deny. A request id has to come from somewhere else, such as a message or link that an agent or app produced. This doc did not find a CLI command that lists pending requests.

Not run in this doc

Assigning a budget to a resource, reading a populated budget, approving a real request, and the conflict error for an already-decided request were not executed. They appear in this doc only as help-text statements.

budgets list needs a session

With only a Public API key it returned auth_forbidden and exit 3. Run it under clay login.

Next steps

  • Read the workspace balance before a run, as in the preflight doc in this batch.
  • Stop a run that is already in progress, as in the cancel doc in this batch.
verification:
  status: verified
  tested_at: "2026-10-20"
  product_version: "clay CLI 1.9.1+d5d2187f50a5"
  command: "clay budgets list | jq '.data | length'"
  expected_result: "A number: 0 in the test workspace, which has no budgets assignable to the signed-in user."

Related Articles