workflow-code CLI
workflow-code is a unified command exposed by @workflow-code/cli. The local command loads the workflow project, installs the global runtime API and executes on the current device; the command to connect to the server is located in the workspace group.
Call Method
The project should have both the Core SDK and CLI installed. The two packages are independently versioned, and it is recommended to pin to the exact verified version:
pnpm add -D workflow-code@0.2.0 @workflow-code/cli@0.2.0
The project must use an exact SemVer in devDependencies.workflow-code; ^, ~, 0.2.x, workspace:*, and local paths are rejected. The exact pin records the development baseline. Runtime compatibility compares only the Core major.minor line, so every patch or dated Alpha on that line runs directly and only a major or minor change requires a CLI or host upgrade. Keep @workflow-code/cli exact as well, but version it independently from Core.
CLI pins Core exactly and constrains peerDependencies.workflow-code to the same minor. For example, a 0.2.7 pin produces >=0.2.0 <0.3.0. Before loading a project module, run, json, structure, resolve-params, and mcp validate the installed Core, the CLI's own pin, and the project's Core declaration; structure also validates the complete workflowCode.projectInfo contract. help does not load a project and skips these checks.
| Scene | Command |
|---|---|
| Project Scripts | pnpm run dev |
| bin installed | pnpm exec workflow-code <command> |
| CLI source repository development | pnpm build && node dist/index.js <command> |
Command Format
workflow-code <command> [workflow-dir] [options] [--] [...args]
| Part | Description |
|---|---|
<command> | run, json, structure, resolve-params, mcp, or help. Displays help when the command is not passed. |
[workflow-dir] | workflow project directory. Use the current directory when not passing. |
[--] [...args] | executor createInput Readable CLI style parameters. -- is used to stop parsing CLI's own options, and subsequent arguments will be passed to workflow as-is. |
Global Options
| Options | Description |
|---|---|
--help / -h | Display help. It must be used as the first argument. |
--json | In the run command, switch to JSON report output; the json command is enabled by default. |
--run-id <id> | Specify the execution ID for this operation. Primarily used to restore waiting_for_input run. |
--entrypoint <id> | Select an entry point for Workflow; use the default entry point if omitted. Applicable to run, json, and resolve-params; Conversation does not accept non-null values. |
--conversation-id <id> | Specify the session ID. Both run and json are usable. |
--file-store-dir <dir> | Specify the local file storage directory. Both run and json are usable. |
--related-project <alias>=<absolute-project-dir> | Bind one relationship confirmed by both project packages for run or json; repeatable. The path must be absolute, and the alias, UUID, and declarations on both sides 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. |
Command List
| Command | Description |
|---|---|
workflow-code run | Execute locally workflow, and in normal mode, output the content of the output node. |
workflow-code json | Execute workflow locally and generate a complete JSON execution report. |
workflow-code structure | Analyze the workflow structure and output JSON. |
workflow-code resolve-params | Read the Composer state from stdin and execute the executor parameter linkage callback. |
workflow-code mcp | Expose Workflow entrypoints to AI clients as standard stdio MCP tools. |
workflow-code help | Output help information. |
Local runtime environment
| Environment variable | Description |
|---|---|
WORKFLOW_KV_STORE_DIR | Local KV store directory. |
WORKFLOW_PERSISTENT_VALUE_STORE_DIR | The local PersistentValue store directory, where the project knowledge base is also stored. |
WORKFLOW_FILE_STORE_DIR | Local file store directory. |
WORKFLOW_DESKTOP_RUNTIME_EVENTS=1 | In json mode, additionally output Desktop consumable runtime event prefix lines. |
WORKFLOW_KV_STORE_DIR and WORKFLOW_PERSISTENT_VALUE_STORE_DIR are independent: the former controls context.storage.local.kv, while the latter controls context.storage.local.persistentValue and local Knowledge. Both isolate the current project by its top-level package.json.id UUID. context.storage.server always uses that project UUID and an authenticated Server connection, independent of both local directories. The project must declare dataStorage.mode; forbidden or unavailable locations fail directly, and local data never synchronizes to Server automatically. --related-project resolves only explicitly supplied directories, never scans parents or siblings, and never makes KV access recurse through a second relationship.
Exit Code
| Situation | Exit Code |
|---|---|
Execution successful, and the payload errCode is 0. | 0 |
| Run failed | 1 |
payload errCode not 0 | 1 |
| Structure analysis failed | 1 |
Output
| Command | stdout/stderr |
|---|---|
run | On success, the output node content is written to stdout; on failure, the JSON report is written to stderr. |
json | The complete execution report is written to stdout. |
structure | The workflow structure JSON is written to stdout. |
resolve-params | Parameter status patch JSON is written to stdout. |
mcp | stdout carries stdio JSON-RPC only; project logs and worker diagnostics go to stderr. |
Parameter separation
If the workflow parameter itself starts with --, it is recommended to write the delimiter explicitly:
workflow-code run . -- --message "hello"
Parameters following the delimiter will be placed into the args array of the selected entrypoint (where Conversation corresponds to executor), and even if the parameter name matches one of CLI’s own options, it will no longer be consumed by workflow-code. For example, workflow-code run . --entrypoint validate -- --entrypoint workflow-owned selects validate and gives the second --entrypoint workflow-owned to the service workflow as it is.