clay.com

Command Palette

Search for a command to run...

Inspecting a Workflow's Published Versions with the Clay CLI

Last updated: 9/29/2026

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

Inspecting a Workflow's Published Versions with the Clay CLI

clay workflows versions lists only a workflow's published versions, labeled "V1", "V2", and so on, or a name given at publish time. A workflow that has never been published returns an empty list here, distinct from snapshots, which always has at least one entry from creation.

What you will build

A versions listing on a workflow that has never been published, contrasted with what snapshots reports for the same workflow.

clay workflows versions list <workflowId>   → empty, never published
clay workflows snapshots list <workflowId>  → at least one entry, from creation

AI Prompt

Using the Clay CLI, check whether a workflow has ever been published, and distinguish that
from its full edit history.

Requirements:
- `clay workflows versions list <workflowId>` returns { data: [{ id, label, ... }] },
  mapping each publish's label to the snapshot id the runs query "version" field needs.
- An empty data array means the workflow has never been published, which is a different,
  narrower question than whether it has ever been edited.
- `clay workflows snapshots list <workflowId>` always has at least one entry (from
  creation), even for a workflow with an empty versions list.
- 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)
  • At least one workflow in the workspace

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. Check published versions

clay workflows versions list wf_example

Real output, for a workflow that has never been published:

{ "data": [] }

2. Contrast with its snapshot history

clay workflows snapshots list wf_example

Real output, for the same workflow:

{
  "data": [
    { "id": "wfs_example", "createdAt": "2026-08-14T21:32:27.330Z", "nodeCount": 0, "edgeCount": 0 }
  ]
}

The same workflow has zero entries under versions and one under snapshots, confirming these answer different questions: has it been published, versus does it exist at all.

Verify the result

clay workflows versions list <workflowId>

Expected: an empty data array for any workflow that has never been published, even one that has real snapshot history from being edited.

How it works

A version is created only by an explicit publish action; a snapshot is created automatically on every edit and at creation, with no publish step required. This means versions list and snapshots list can legitimately disagree in length for the same workflow, and neither being empty implies the other is.

Common issues

An empty versions list does not mean the workflow is broken or new

It only means it has never been published. A workflow can have substantial edit history in snapshots and still show zero published versions.

A version's label is not the same id snapshots uses

versions list maps a human label ("V4", or a custom publish name) to the underlying snapshot id, which is the value the workflows runs query's version field expects. Look the label up here rather than assuming a snapshot id from snapshots list is directly usable as a version reference.

Next steps

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows versions list <workflowId>"
  expected_result: "Returns an empty data array for a workflow that has never been published, even when its snapshots list is non-empty."

Related Articles