Validate, publish, restore

Shipping a workflow is a three-verb discipline: validate before publishing, publish deliberately, and know that restore has your back for everything inside the definition.

Validate

cai workflow validate

Validation reports structural issues with concrete codes — run it after any significant surgery, not just before publishing:

Issue	Meaning
ORPHAN_NODE	A node with no connection to the rest of the graph (multi-node flows).
UNLINKED_SUBFLOW_CALLER	A Run flow node whose target flow is missing or unlinked.
DANGLING_TYPE_REFERENCE	An expression references a deleted custom type.
BRANCH_INVALID	An If/Else or Router branch problem — blank condition, missing Else.
Trigger lifecycle issues	Armed test events, disabled canvases, shadowed triggers — the same set as cai trigger audit.

Warnings are advisory; blockers stop a publish.

Publish

cai workflow publish

Publishing copies the development state to the live rail as a numbered, immutable release (the full model). The pre-flight checklist that saves the day:

1. Triggers enabled first — the enabled flag ships inside the published state; toggling after publish does nothing live.
2. Test events disarmed — publishing with an enabled trigger still armed makes one real event run both rails, both metered. The publish API refuses without explicit acknowledgment; disarm instead of acknowledging, almost always.
3. Live data store ready — publish copies no records; seed with cai data copy-to-live if the live flow expects data.
4. Blast radius known — cai deps lists the live agents this release will change immediately.

Publish can also refuse for plan limits (active-workflow cap) or a stale base state (the dev head moved — re-read and retry).

Restore

cai workflow history
cai workflow restore <stateId>

Every save of the development version is a restorable state. Restore appends a new dev state with the old content — non-destructive, the pre-restore draft stays in history. Edit boldly; nothing inside the graph is unrecoverable.

What restore does not touch: records (the data store is unversioned), live releases (restore is a dev-rail operation — publish to change live), and anything that already happened externally. Version history is plan-gated (unavailable on free, 90 days on standard plans).

For agents, the equivalent gate is cai agent publish-preflight — and agent versions have no restore; recovery is forward-only (publishing an agent).

Example prompts

Validate this workflow, explain every issue code it returns, fix the blockers, and rerun until clean — then stop before publishing.

Publish this workflow: check triggers are enabled and disarmed, seed the live store from dev, show me cai deps first, then publish and confirm the release number.