Skip to content

ptkl workflow

Manage project workflows — CRUD, triggering, and execution control — from the command line.

Overview

ptkl workflow covers the full lifecycle of the platform's workflow engine: creating and editing workflow definitions, triggering and publishing events, and inspecting/controlling in-flight executions (pause/resume/kill/restart at both the execution and individual-node level). It maps onto the SDK Workflow client (@ptkl/sdk/beta).

Subcommands

Subcommand Description
list List all workflows for the current project
get Get a workflow by name or UUID
settings Get settings for a workflow
create Create a new workflow
update Update an existing workflow
delete Delete a workflow
trigger Trigger a workflow's event handler by workflow ID
publish Publish an event to every workflow subscribed to it
install Create and publish a workflow in one call
history list / history get Inspect workflow execution history
running list / running get Inspect currently running workflow executions
pause / resume / kill / restart Execution-level control
node pause / node resume / node kill Node-level control within a running execution
errors list / errors remove / errors clear Manage workflow execution errors

CRUD

ptkl workflow list

List all workflows for the current project.

ptkl workflow list

ptkl workflow get

Get a workflow by name or UUID.

ptkl workflow get -r <ref>

ptkl workflow get --ref onboarding-flow

ptkl workflow settings

Get the settings block for a workflow.

ptkl workflow settings -r <ref>

ptkl workflow settings --ref onboarding-flow

ptkl workflow create

Create a new workflow.

ptkl workflow create -d <json>
Option Description
-d, --data <json> Workflow payload as a JSON string (name, dev_version, public_version, integrator, roles, settings) (required) 
ptkl workflow create --data '{"name":"onboarding-flow","dev_version":{"nodes":[]},"integrator":"my-app"}'

ptkl workflow update

Update an existing workflow.

ptkl workflow update <id> -d <json>
Argument/Option Description
<id> Workflow UUID (required)
-d, --data <json> Workflow payload as a JSON string (name, dev_version, public_version, integrator, roles, settings) (required) 
ptkl workflow update f81d4fae-... --data '{"public_version":{"nodes":[...]}}'

ptkl workflow delete

Delete a workflow.

ptkl workflow delete <id>

ptkl workflow delete f81d4fae-...

Triggering

ptkl workflow trigger

Trigger a workflow's event handler directly by workflow ID.

ptkl workflow trigger <id> <event> [-d <json>]
Argument/Option Description
<id> Workflow UUID (required)
<event> Event name (required)
-d, --data <json> Event payload as a JSON string (default: {}) 
ptkl workflow trigger f81d4fae-... user.created --data '{"userId":"u_123"}'

ptkl workflow publish

Publish an event to every workflow subscribed to it (fan-out, no target workflow ID needed).

ptkl workflow publish <event> [-d <json>]

ptkl workflow publish user.created --data '{"userId":"u_123"}'

ptkl workflow install

Create and publish a workflow in one call. Rejects if a workflow with the same name + integrator already exists — use this for idempotent installs from a Forge app's install script.

ptkl workflow install -d <json>
Option Description
-d, --data <json> Install payload as a JSON string (name, settings, project_uuid, dev_version, public_version, integrator) (required) 
ptkl workflow install --data '{"name":"onboarding-flow","integrator":"my-app","dev_version":{"nodes":[]}}'

History & running executions

ptkl workflow history list

List workflow execution history, grouped by context.

ptkl workflow history list [--limit <n>] [--offset <n>] [--status <status>] [--ref <ref>] [--type <type>] [--workflow-name <name>] [--context-uuid <uuid>] [--date-from <date>]

ptkl workflow history list --ref onboarding-flow --status failed --limit 20

ptkl workflow history get

Get a single workflow execution history entry.

ptkl workflow history get <exec>

ptkl workflow history get 9c1e2f3a-...

ptkl workflow running list

List currently running workflow executions.

ptkl workflow running list [--limit <n>] [--offset <n>] [--status <status>] [--type <type>] [--ref <ref>] [--workflow-name <name>] [--context-uuid <uuid>]

ptkl workflow running list --ref onboarding-flow

ptkl workflow running get

Get a single running workflow execution.

ptkl workflow running get <exec>

ptkl workflow running get 9c1e2f3a-...

Execution control

ptkl workflow pause / resume / kill

Pause, resume, or kill a running/paused workflow execution.

ptkl workflow pause <exec>
ptkl workflow resume <exec>
ptkl workflow kill <exec>

ptkl workflow pause 9c1e2f3a-...
ptkl workflow resume 9c1e2f3a-...
ptkl workflow kill 9c1e2f3a-...

ptkl workflow restart

Restart a failed/killed workflow execution from history.

ptkl workflow restart <exec> [--clear-state]
Option Description
--clear-state Discard prior node state instead of a smart resume 
ptkl workflow restart 9c1e2f3a-... --clear-state

Node-level control

Pause, resume, or kill a single node within a running workflow execution — useful for stepping through or debugging a loop/branch without stopping the whole execution.

ptkl workflow node pause <exec> <nodeId> [--iteration-idx <n>] [--parent-node-id <id>]
ptkl workflow node resume <exec> <nodeId> [--iteration-idx <n>] [--parent-node-id <id>]
ptkl workflow node kill <exec> <nodeId> [--iteration-idx <n>] [--parent-node-id <id>]
Option Description
--iteration-idx <n> Iteration index (for nodes inside a loop)
--parent-node-id <id> Parent node ID (for nodes inside a loop) 
ptkl workflow node pause 9c1e2f3a-... 12
ptkl workflow node resume 9c1e2f3a-... 12 --iteration-idx 3 --parent-node-id 7

Errors

ptkl workflow errors list

List workflow execution errors.

ptkl workflow errors list

ptkl workflow errors remove

Remove a single workflow execution error.

ptkl workflow errors remove <id>

ptkl workflow errors remove 42

ptkl workflow errors clear

Remove all workflow execution errors.

ptkl workflow errors clear

Typical Workflow

# 1. Install a workflow idempotently (e.g. from a Forge app's install script)
ptkl workflow install --data '{"name":"onboarding-flow","integrator":"my-app","dev_version":{"nodes":[]}}'

# 2. Trigger it
ptkl workflow trigger f81d4fae-... user.created --data '{"userId":"u_123"}'

# 3. Watch what's running
ptkl workflow running list --ref onboarding-flow

# 4. Something's stuck — pause it, inspect, then resume or kill
ptkl workflow pause 9c1e2f3a-...
ptkl workflow running get 9c1e2f3a-...
ptkl workflow resume 9c1e2f3a-...

# 5. Clean up dead-lettered errors once resolved
ptkl workflow errors clear

See Also