workflow-code run
workflow-code run Loads a workflow directory on the local device, installs the global workflow runtime API, executes the createInput and workflow run of the selected entry (Conversation, executor), and outputs the result in normal CLI mode.
This command supports only Workflow and Conversation. Kanban is a static HTML project that returns an explicit workflow execution not supported error; inspect it with workflow-code structure, then preview it in the Desktop or a published Embed.
Command Format
workflow-code run [workflow-dir] [--entrypoint <id>] [--json] [--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 |
|---|---|
--json | Toggles to JSON report output. The behavior is close to workflow-code json. |
--entrypoint <id> | Run specifies the Workflow entry; use defaultEntrypoint when omitted. Conversation Passing a non-null value will result in failure. |
--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. State read-write significance only for items that declare executor.projectType: "conversation". |
--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 related-project directory; repeatable. The two packages must confirm the relationship, and UUID and alias must match. |
--resolved-user-inputs-json <json> | Injects an array of submitted user input or tool approval answers. |
--tool-permissions-json <json> | Host-passed tool permission override policy; for regular manual CLI debugging, it is usually not required. |
Execution process
| Phase | Description |
|---|---|
| Analysis Directory | workflow-dir uses the current directory by default. |
| Load Environment | Execute before loading workflow directory .env. |
| Select entrance | Workflow Press --entrypoint or defaultEntrypoint to select the execution configuration;Conversation uses executor itself. |
| Create Input | Invokes the createInput(context) of the selected entry or Conversation executor. |
| Execute workflow | Only workflow.run(input, context) of the selected configuration is called, and the normal node will trigger CLI output hooks. |
| Set Exit Code | The exit code is 1 if workflow fails, pauses waiting for input, or payload errCode is not 0. |
Output
| Situation | Output |
|---|---|
Successful and not forwarded --json | The contents of the output node are written to stdout. |
Failed and not passed --json | The full JSON execution report is written to stderr. |
waiting_for_input and not passed --json | It does not interactively read from stdin; we recommend using workflow-code json to view pendingUserInput and restore it instead. |
Imported --json | The full JSON execution report is written to stdout. |
Example
workflow-code run .
workflow-code run . --entrypoint validate -- --message "Validate only"
workflow-code run workspace/workflow/hello -- --message "hello"
workflow-code run workspace/workflow/runtime-timer -- --title "Fixture Timer" --milliseconds 2000
workflow-code run . --conversation-id demo -- --message "Continue"
workflow-code run . --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 run workspace/workflow/conversation-knowledge --conversation-id demo -- --message "Record today's conclusion"
workflow-code run . --json -- --message "debug"
Precautions
| Scene | Recommendation |
|---|---|
The workflow parameter starts with --. | Using the delimiter --, the parameters following the delimiter will be passed to workflow as-is. |
workflow also defines the --entrypoint parameter | The entry selection of CLI is placed before the separator; the parameter with the same name after the separator enters the service args as it is. |
| Need to check node report | Use --json or use workflow-code json instead. |
| User input or tool approval needs to be restored. | Use the same --run-id and --resolved-user-inputs-json; during debugging, prioritize using workflow-code json. |
| A stable session is required. | Explicitly pass --conversation-id, otherwise the session ID may be generated by runtime based on input. |
| workflow calls PersistentValue or a Knowledge helper | Pass context.storage.local or .server explicitly. Local uses WORKFLOW_PERSISTENT_VALUE_STORE_DIR; server uses the project UUID and WORKFLOW_SERVER_URL / WORKFLOW_SERVER_ADMIN_KEY or workspace login. A forbidden or unavailable location fails without fallback or synchronization. |
| workflow accesses related-project KV | Repeat --related-project for every direct relationship. CLI validates the directory, UUID, alias, and both current declarations. A one-sided pending relationship is unavailable, and resolution never recurses through the target's other relationships. |
workflow call context.files.createFile(...) | The local operation reads the connection to the same server and uploads it to the server file API. If the server is not connected, the call will report an error and will not be written to the local file store. |