Auditing Claygents in a Workspace with the Clay CLI

clay claygents lists and deletes the Claygent instances created in a workspace, independent of which campaign or workflow references them. It is a small, two-command group: a full audit of what exists, and a way to remove one.

What you will build

A listing of real Claygents in a workspace, and a look at what deleting one actually removes.

clay claygents list
    ↓
clay claygents delete <claygentId>

AI Prompt

Using the Clay CLI, list the Claygents that exist in a workspace and understand what
deleting one affects.

Requirements:
- `clay claygents list` returns { data: [{ id, name, currentVersionId }] }, one entry per
  Claygent regardless of where it is referenced from.
- `clay claygents delete <claygentId>` removes the Claygent itself. This command has no
  --dry-run or reference-check equivalent to `audiences fields segments`: nothing in this
  group reports which campaigns or workflows currently reference a Claygent before deleting it.
- Run the verification step below before finishing.

Using the Clay CLI, list the Claygents that exist in a workspace and understand what
deleting one affects.

Requirements:
- `clay claygents list` returns { data: [{ id, name, currentVersionId }] }, one entry per
  Claygent regardless of where it is referenced from.
- `clay claygents delete <claygentId>` removes the Claygent itself. This command has no
  --dry-run or reference-check equivalent to `audiences fields segments`: nothing in this
  group reports which campaigns or workflows currently reference a Claygent before deleting it.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)

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. List Claygents

clay claygents list

clay claygents list

Real output:

{
  "data": [
    { "id": "c_example", "name": "Prospect Scoring Specialist", "currentVersionId": "cv_example" }
  ]
}

{
  "data": [
    { "id": "c_example", "name": "Prospect Scoring Specialist", "currentVersionId": "cv_example" }
  ]
}

currentVersionId identifies the Claygent's current published version. There is no separate command in this group to list a Claygent's version history.

Verify the result

clay claygents list

clay claygents list

Expected: an array of every Claygent in the workspace, each with a stable id and its currentVersionId, regardless of whether it is currently referenced by a campaign's update-claygent settings or a workflow node.

How it works

Claygents exist as workspace-level resources independent of any single campaign or workflow: the same Claygent id can be referenced from a campaign's Claygent settings and from elsewhere in the workspace at once. claygents list is the only enumeration of them from the CLI, and it reports the full set regardless of reference count.

Common issues

No reference check before delete

Unlike audiences fields segments, there is no claygents-side command to see what currently points at a given Claygent id before deleting it. Confirm elsewhere in the workspace (for example, each campaign's update-claygent configuration) that a Claygent is unused before deleting it.

`currentVersionId` is not the same as the Claygent's own id

Passing a currentVersionId value where a claygentId is expected (for example to claygents delete) targets the wrong resource. Use the id field from claygents list.

Next steps

Functions vs. Routines with the Clay CLI

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay claygents list"
  expected_result: "Returns every Claygent in the workspace as { id, name, currentVersionId }, independent of where each is referenced."

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay claygents list"
  expected_result: "Returns every Claygent in the workspace as { id, name, currentVersionId }, independent of where each is referenced."