workspace run

workspace run Invoke Workflow Server’s run API, executing workflow on the remote draft, latest, or a specified online version.

This command supports only Workflow and Conversation. Kanban does not generate a run record, and the server returns an explicit error that the static project does not support execution.

CLI During execution, API key owner will be used as the actor to write the server run record. The project must be bound to a top-level package.json.id UUID, and the current account must simultaneously meet the following conditions: “project visibility, execution permissions, and not being prohibited from running by a run block.”

Command Format

pnpm exec workflow-code workspace run <workflow> [--target draft|latest|version] [--entrypoint <id>] [--] [...args]

Parameter

Parameter	Description
<workflow>	Local workflow directory name, workflow name, or directly pass a remote project UUID.
args	An array of args was sent to the server running API.
--target <target>	Operational objectives. Default latest.
--entrypoint <id>	Workflow Entrance. When omitted, the default entry point of the target version is used; Conversation passing a non-null value will return 400.

Target

Value	Description
latest	Default value. Run the current latest version.
draft	Run the remote draft. Suitable for pre-release validation.
Specific version number	Run the specified online version. The preparing or offline version is rejected by the server.

Parameter parsing rules

Workspace CLI recognizes its own global options before an explicit --. Unrecognized parameters are retained in the args array; -- itself is stripped, and all later parameters are passed through unchanged.

Scene	Writing style
Common business parameters	run hello -- --message "hello"
Specify target and entry	run hello --target draft --entrypoint validate -- --message "hello"
Business parameters are also referred to as --entrypoint	run hello --entrypoint validate -- --entrypoint workflow-owned; the former selects the entry point, while the latter passes the business arguments.

API

Steps	Endpoint
Remote Run	POST /api/workflows/{workflow}/run

The request body contains target, optional entrypointId and args, and is also compatible with entrypoint_id. When calling HTTP API directly, you can use version as an alias for a specific version number; if target is not provided, the server will treat version as the runtime target. Server will check the entrance according to the accurate target before entering the queue, and the unknown entrance will return 400 with the allowed entrance and default entrance attached.

Output

Situation	Output
Run succeeds	Server run API JSON.
workflow payload errCodeNon0	The server returned error semantics with the CLI exit code1.
Not logged in	Output error message with exit code 1.
403	CLI It will distinguish between “no project permissions” and “the current account has been banned from running this project,” rather than issuing a generic prompt to log in again.

Example

pnpm exec workflow-code workspace run hello -- --message "hello"
pnpm exec workflow-code workspace run hello --target latest --entrypoint main -- --message "hello"
pnpm exec workflow-code workspace run hello --target draft --entrypoint validate -- --message "draft test"
pnpm exec workflow-code workspace run conversation-knowledge --target draft -- --message "Record today's conclusion" --title "Demo conversation"

If you need to specify a stable_conversation_idfor conversation workflow, directly call the server run API;workspace runcurrently only sendstargetandargs:

curl -X POST "$WORKFLOW_SERVER_URL/api/workflows/conversation-knowledge/run" \
  -H "Authorization: Bearer $WORKFLOW_SERVER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "draft",
    "conversation_id": "demo-thread",
    "args": ["--message", "Record today's conclusion", "--title", "Demo conversation"]
  }'

Related Commands

Goal	Command
Single-node debugging	debug-node
View available versions	versions