Rendering a Workflow as a Diagram with the Clay CLI

clay workflows diagram renders a workflow's current graph as a Mermaid flowchart string, ready to paste into anything that renders Mermaid. An empty workflow renders as a single labeled placeholder node rather than an error or a blank string.

What you will build

A diagram render of a workflow that has not been built out yet, to see the real placeholder shape before building against a populated one.

clay workflows diagram <workflowId>

AI Prompt

Using the Clay CLI, render a workflow's graph as a Mermaid diagram.

Requirements:
- `clay workflows diagram <workflowId>` returns { format: "mermaid", diagram: <string> }.
- A workflow with no nodes renders as a single-node flowchart labeled "(empty workflow)",
  not an error and not an empty string.
- The returned string is a complete Mermaid `flowchart TD` definition, usable directly in
  any Mermaid renderer.
- Run the verification step below before finishing.

Using the Clay CLI, render a workflow's graph as a Mermaid diagram.

Requirements:
- `clay workflows diagram <workflowId>` returns { format: "mermaid", diagram: <string> }.
- A workflow with no nodes renders as a single-node flowchart labeled "(empty workflow)",
  not an error and not an empty string.
- The returned string is a complete Mermaid `flowchart TD` definition, usable directly in
  any Mermaid renderer.
- 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. Render an empty workflow

clay workflows diagram wf_example

clay workflows diagram wf_example

Real output:

{
  "format": "mermaid",
  "diagram": "flowchart TD\n    empty[\"(empty workflow)\"]"
}

{
  "format": "mermaid",
  "diagram": "flowchart TD\n    empty[\"(empty workflow)\"]"
}

Verify the result

clay workflows diagram <workflowId>

clay workflows diagram <workflowId>

Expected: format: "mermaid" with a diagram string that is always a syntactically complete Mermaid definition, including for a workflow with zero nodes.

How it works

The command renders whatever workflows graph get would report structurally, translated into Mermaid syntax rather than the raw node/edge JSON. Because it always produces a complete, valid diagram string, code that pipes this output straight into a Mermaid renderer does not need to special-case an empty workflow separately; the placeholder node renders correctly on its own.

Common issues

A one-node diagram does not necessarily mean a working workflow

The "(empty workflow)" placeholder is visually a single box, easy to mistake for a minimal real workflow at a glance rather than a workflow that has not been built out at all. Cross-check with clay workflows graph get (nodeCount) when the distinction matters.

Next steps

Discovering Workflows and Their Graphs

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows diagram <workflowId>"
  expected_result: "Returns a complete Mermaid flowchart string, rendering a single \"(empty workflow)\" placeholder node for a workflow with zero nodes."

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows diagram <workflowId>"
  expected_result: "Returns a complete Mermaid flowchart string, rendering a single \"(empty workflow)\" placeholder node for a workflow with zero nodes."