steamharness json
steamharness 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
steamharness 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 STEAMHARNESS_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. CLI Web can pass in tool permission overrides; regular CLI uses the defaults registered by executor and tools when omitted. |
--json | Compatible options; the command already outputs JSON by default. |
Report Structure
| Field | Description |
|---|---|
runId | The ID of the local execution. |
projectName | 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 |
|---|---|
STEAMHARNESS_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 __STEAMHARNESS_RUNTIME_EVENT__, which hosts consume for streaming execution events. Normal scripts should close the environment variable when parsing the final JSON.
PersistentValue
steamharness json configures storage from the project's dataStorage.mode. context.storage.local.kv uses STEAMHARNESS_KV_STORE_DIR; context.storage.local.persistentValue and local Knowledge use STEAMHARNESS_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 STEAMHARNESS_SERVER_URL / STEAMHARNESS_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
steamharness json .
steamharness json . --entrypoint validate -- --message "Validate only"
steamharness json ./conversation-project --conversation-id demo -- --message "Continue"
steamharness json . --related-project inventory=/srv/workflows/inventory -- --message "Read inventory"
STEAMHARNESS_KV_STORE_DIR="$PWD/.workflow-kv" \
STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR="$PWD/.workflow-persistent-values" \
steamharness json workspace/workflow/conversation-knowledge --conversation-id demo -- --message "Record today's conclusion"
steamharness json workspace/workflow/hello -- --message "hello"
steamharness 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:
steamharness json . -- --message "deploy"
Tool Approval
When workflow uses executor.tools and workflow.createToolApprovalGate() for tool approvals, CLI uses the registration defaults. Enabled tools that need approval return waiting_for_input and pendingUserInput; resume with the same runId and --resolved-user-inputs-json. CLI Web uses --tool-permissions-json to preserve the run's policy snapshot across user-input recovery.
After submitting the answer, restore with the same runId and requestId:
steamharness 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 |