workflow-code json
workflow-code json uses the same execution path as run --json, but outputs a full execution report by default. It is suitable for debugging node order, error messages, output node results, and session IDs.
This command supports only Workflow and Conversation. Kanban does not produce run report and returns an explicit error "workflow execution is not supported" when called.
Command Format
workflow-code json [workflow-dir] [--entrypoint <id>] [--run-id <id>] [--conversation-id <id>] [--file-store-dir <dir>] [--related-project <alias>=<absolute-project-dir>] [--resolved-user-inputs-json <json>] [--tool-permissions-json <json>] [--] [...args]
Parameter
| Parameter | Description |
|---|---|
workflow-dir | workflow project directory. Use the current directory when not passing. |
args | The createInput({ args }) readable array of raw parameters for the selected entry (Conversation, executor). |
Options
| Options | Description |
|---|---|
--entrypoint <id> | Run to specify the Workflow entry; use the default entry when omitted. Conversation does not accept non-null values. |
--run-id <id> | Specify the execution ID for this operation. Used to restore the same runId during waiting_for_input run. |
--conversation-id <id> | Specify the session ID. |
--file-store-dir <dir> | Specify the local file storage directory. Read WORKFLOW_FILE_STORE_DIR when not passed. |
--related-project <alias>=<absolute-project-dir> | Explicitly provide one relationship confirmed by both projects; repeatable, with no directory scanning. |
--resolved-user-inputs-json <json> | Injects an array of submitted user input answers. Each entry contains requestId, nodeName, values, submittedAt. |
--tool-permissions-json <json> | Host-specific parameters. Desktop/server can be used to pass in override values for tool permissions; for regular CLI, when no value is passed, the default values registered by executor and tools are used entirely. |
--json | Compatible options; the command already outputs JSON by default. |
Report Structure
| Field | Description |
|---|---|
runId | The ID of the local execution. |
workflowName | The name of the workflow that was actually executed. |
entrypointId / entrypointTitle | Workflow Snapshot of the actual entry and its header; omitted in Conversation. |
status | running, waiting_for_input, success, failed, aborted, or timed_out. |
definedNodes | The node definition to be statically analyzed. |
registry | executor List of registered debug nodes. |
nodes | Actual executed node report. |
outputs | A successful output node result named output. |
pendingUserInput | waiting_for_input, including the form params and the default value. |
resolvedUserInputs | This run has been submitted and injected with runtime user input answer. |
result | workflow Final result or standard error. |
Runtime event output
| Configuration | Behavior |
|---|---|
WORKFLOW_DESKTOP_RUNTIME_EVENTS=1 | Output the prefixed runtime event lines additionally before the final JSON. |
| Not set | Only the final JSON report is output. |
The runtime event prefix is __WORKFLOW_CODE_RUNTIME_EVENT__, which is used to Desktop consume streaming running events. Normal scripts should close the environment variable when parsing the final JSON.
PersistentValue
workflow-code json configures storage from the project's dataStorage.mode. context.storage.local.kv uses WORKFLOW_KV_STORE_DIR; context.storage.local.persistentValue and local Knowledge use WORKFLOW_PERSISTENT_VALUE_STORE_DIR. Both are isolated by project UUID and remain separate storage kinds. context.storage.server uses the top-level project UUID and WORKFLOW_SERVER_URL / WORKFLOW_SERVER_ADMIN_KEY or workspace CLI workflow-auth.json. The two locations never fall back to or synchronize with each other; a forbidden or unavailable backend throws. --related-project binds explicit related projects and follows the location of the current local/server call exactly. context.files.createFile(...) still uses the server connection.
Example
workflow-code json .
workflow-code json . --entrypoint validate -- --message "Validate only"
workflow-code json ./conversation-project --conversation-id demo -- --message "Continue"
workflow-code json . --related-project inventory=/srv/workflows/inventory -- --message "Read inventory"
WORKFLOW_KV_STORE_DIR="$PWD/.workflow-kv" \
WORKFLOW_PERSISTENT_VALUE_STORE_DIR="$PWD/.workflow-persistent-values" \
workflow-code json workspace/workflow/conversation-knowledge --conversation-id demo -- --message "Record today's conclusion"
workflow-code json workspace/workflow/hello -- --message "hello"
workflow-code json workspace/workflow/runtime-timer -- --title "Fixture Timer" --milliseconds 2000
The report of the runtime-timer example will contain a timers record of the success state, and durationMs will be close to the incoming --milliseconds.
Restore User Input Node
CLI does not interactively read user input from stdin. When workflow.createUserInputNode(...) is encountered, the report goes into waiting_for_input and contains pendingUserInput:
workflow-code json . -- --message "deploy"
Tool Approval
When workflow uses the executor.tools and workflow.createToolApprovalGate() registration tool approvals,CLI defaults to only the registration defaults. If the tool is enabled but not automatically approved,CLI will output waiting_for_input and pendingUserInput like a normal user-input, and the caller will resume with the same runId and --resolved-user-inputs-json. Desktop and server runner will additionally use --tool-permissions-json to transfer the policy snapshot of this run, and continue to pass in the same policy when restoring user-input to avoid losing user selection after approval.
After submitting the answer, restore with the same runId and requestId:
workflow-code json . \
--run-id 20260604-abcd \
--resolved-user-inputs-json '[{"requestId":"demo:20260604-abcd:approval","nodeName":"approval","values":{"approved":true},"submittedAt":"2026-06-04T10:00:00.000Z"}]' \
-- --message "deploy"
Exit Code
| Situation | Exit Code |
|---|---|
workflow succeeded and the payload errCode is 0 | 0 |
workflow Pause to waiting_for_input | 1; The errCode of the report payload is 202, which can be restored with the same runId. |
| workflow error thrown or execution failed | 1 |
payload errCode not 0 | 1 |