CLI Reference

Workflow Commands

workflow init

Scaffold an attribute-based workflow skeleton.

bin/cake workflow init order Orders
bin/cake workflow init order Orders --migration   # also scaffold the state-column migration

With --migration the command additionally writes a migration that adds the state column (default state, see --field) to the table, into config/Migrations (override with --migrations-path). The output then walks you through adding the behavior and points you to the convenience traits and panel() view helper.

workflow list

List configured workflows.

bin/cake workflow list
bin/cake workflow list --verbose

workflow show

Show one workflow in detail.

bin/cake workflow show order
bin/cake workflow show order --mermaid

workflow batch

Apply a transition to all records currently in a given state — for mass-advancing records and scheduled batch jobs.

bin/cake workflow batch order pay --state pending
bin/cake workflow batch order pay --state pending --limit 500 --reason "nightly run"
bin/cake workflow batch order pay --state pending --dry-run         # just count
bin/cake workflow batch order pay --state pending --stop-on-failure

Each record is transitioned through the behavior (save + log, plus lock when enabled). The command prints how many succeeded/failed and exits non-zero if any failed.

The --mermaid option prints a Mermaid flowchart definition you can paste into Markdown, an issue, or this documentation. It renders like this:

workflow apply

Apply a transition to a single record from the command line — handy for ops, debugging, and scripted/cron-driven transitions.

bin/cake workflow apply order 42 pay
bin/cake workflow apply order 42 pay --reason "manual capture" --user 7
bin/cake workflow apply order 42 pay --dry-run

It loads the record, runs the transition through the behavior (save + log, plus lock when enabled), and prints the outcome. --dry-run only checks whether the transition is allowed. Exit code is non-zero when the transition is blocked, locked, errored, or the record is missing.

The transition audit trail is browsable in the admin UI (/admin/workflow/transitions).

workflow validate

Validate one or more workflows and surface analyzer findings: unreachable states, dead-end states, transitions to/from invalid or terminal states, and automatic states that have only conditional transitions and no unconditional fallback (which can leave an item stuck). The fallback finding is a warning by default and a hard error when Workflow.strictMode is enabled. With --check-data it also reports records sitting in states that no longer exist (orphaned records).

bin/cake workflow validate
bin/cake workflow validate order --check-data

workflow migrate

Move orphaned records (whose state was removed/renamed) forward to a valid state. Refuses to run if any orphaned state lacks a mapping; runs atomically and logs each move. See Drift Safety.

bin/cake workflow migrate order --map old_state:new_state,legacy:pending
bin/cake workflow migrate order --map legacy:pending --dry-run

workflow timeouts

Process due timeouts.

bin/cake workflow timeouts
bin/cake workflow timeouts --dry-run
bin/cake workflow timeouts --limit 100

Bake Commands

bake workflow_state

Requires cakephp/bake and the Bake plugin.

bin/cake bake workflow_state Order/Shipped
bin/cake bake workflow_state Order/Shipped --final
bin/cake bake workflow_state Order/Shipped --transition-to Delivered --transition-name deliver