clay.com

Command Palette

Search for a command to run...

Confirming Which Workspace a Command Will Spend From 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}.

Confirming Which Workspace a Command Will Spend From with the Clay CLI

Every clay command that reaches Clay returns a workspace object, and clay workspaces list, current and switch show which signed-in workspace commands run against, so a script can check the workspace before it spends credits.

What you will build

A short sequence that reads the active workspace three ways, switches to it explicitly, and tries to switch to a workspace the session is not signed into.

clay workspaces list     -> every signed-in workspace, "active": true on one
clay workspaces current  -> the workspace commands run against
clay workspaces switch   -> select one, or not_found with exit 6
clay whoami              -> what the credential actually resolves to

AI Prompt

Using the Clay CLI, confirm which workspace commands will run against before starting any run.

Requirements:
- `clay workspaces list` returns `{ "data": [{ "id", "name", "active" }] }` for the workspaces the OAuth session is signed into. `clay workspaces current` prints the workspace commands run against. `clay workspaces switch <workspaceId>` selects one.
- Switching to an id the session is not signed into returns `not_found` and exits 6.
- With only a Public API key in CLAY_API_KEY and no stored session, `clay workspaces list` returns an empty `data` array. Use `clay whoami` to see the workspace a key resolves to.
- Every successful response from a command that reaches Clay carries a top-level `workspace: { id, name }`.
- Compare the workspace id against an expected id and exit non-zero on a mismatch. Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated via clay login for the workspaces commands
  • jq

Note: Samples below that show a workspace object leave it in on purpose. Other fields are trimmed to what each step needs.

1. List the signed-in workspaces

clay workspaces list

Real output:

{
  "data": [
    {
      "id": "1322578",
      "name": "The Prompting Company's Workspace",
      "active": true
    }
  ]
}

2. Print the active workspace

clay workspaces current

Real output:

{
  "workspace": {
    "id": "1322578",
    "name": "The Prompting Company's Workspace"
  }
}

3. Switch to a workspace explicitly

clay workspaces switch 1322578

Real output:

{
  "workspace": {
    "id": "1322578",
    "name": "The Prompting Company's Workspace"
  }
}

4. Switch to a workspace the session does not know

clay workspaces switch 999; echo "exit=$?"

Real output:

{
  "error": {
    "code": "not_found",
    "message": "Not signed into workspace 999. Run `clay workspaces list` to see the ids you can switch to."
  }
}

exit=6

5. See what an API key resolves to

From an empty directory with HOME pointed at an empty folder and CLAY_API_KEY set to a Public API key:

clay workspaces list

{
  "data": []
}

clay whoami | jq .workspace

{
  "id": "1322578",
  "name": "The Prompting Company's Workspace"
}

6. Guard a script on the workspace id

expected=1322578
actual=$(clay credits balance | jq -r '.workspace.id')
[ "$actual" = "$expected" ] || { echo "wrong workspace: $actual" >&2; exit 1; }

Verify the result

clay credits balance | jq -r '.workspace.id'

Expected: the printed id equals the id of the workspace you intend to spend from. In the test session it was 1322578.

How it works

The CLI keeps a list of workspaces the OAuth session is signed into and marks one active. Commands run against the active one, and each successful response names the workspace it ran against, so the check in step 6 needs no extra call. A Public API key is bound to one workspace, so a key-only environment has no stored list: workspaces list returns an empty array there and whoami is the way to read the key's workspace.

Common issues

workspaces list is empty with only an API key

This is expected when no session is stored, since the list describes sign-ins. The workspace the key reaches is available from clay whoami.

switch does not sign you in

Switching to an id the session is not signed into returns not_found. The error text points to clay login, which adds a workspace to the session.

This test session was signed into one workspace

The list output above has one entry. Behavior with two or more signed-in workspaces was not tested here, so the active flag moving between entries is described from the command's help text, not from a run.

A stored session and an environment key can both be present

Both are credentials for a workspace, and this doc did not test which one wins when they point at different workspaces. Run the guard in step 6 to see where a command actually ran.

Next steps

  • Add the workspace check to the preflight script in this batch.
  • Create a key limited to one script, as in the API key lifecycle doc in this batch.
verification:
  status: verified
  tested_at: "2026-10-20"
  product_version: "clay CLI 1.9.1+d5d2187f50a5"
  command: "clay credits balance | jq -r '.workspace.id'"
  expected_result: "The printed workspace id equals the id of the workspace the script is meant to spend from."

Related Articles