Server Workspace CLI
Both workspace and local commands are provided by @workflow-code/cli. It can package, upload, publish, and download Workflow, Conversation, and Kanban projects; only Workflow/Conversation supports remote running and node debugging. Use the unified workflow-code workspace prefix after installation; Repository source code development can also be called through the workspace script:
pnpm exec workflow-code workspace <command> [args]
It is used to connect Workflow Server and manage remote workflow packages and versions.
Parameter Rules
workspace CLI recognizes global options before explicit --, unrecognized arguments are left as command positional arguments or workflow args. -- itself is stripped, and all subsequent parameters are passed to workflow as they are.
| Rules | Description |
|---|---|
| Global Options | --server, --token, --target, --entrypoint, --release-log, --source-mode, --path, --file, --output, --no-wait, --create are parsed by CLI before the delimiter. |
| workflow args | run is followed by <workflow>, parameters that are not recognized as global options are sent to server run API. |
| Debug arguments | Arguments after <workflow> and <node> in debug-node that are not recognized as global options are sent to the debug node API. |
| parameter separation | When the business parameter has the same name as the CLI option, -- is written after the CLI option. |
--version | Abandoned. The version number is generated by the server release process. |
Global Options
| Options | Description |
|---|---|
--server <url> | Workflow Server address. By default, WORKFLOW_SERVER_URL is read, the saved CLI login status is read, and finally the http://localhost:7125 commonly used for development is returned. The deployment environment recommends explicitly passing the official domain name or your server address. |
--token <token> | Optional explicit Bearer override value. By default, WORKFLOW_SERVER_ADMIN_KEY is read, and then the saved CLI login status API Key is read. |
--target <target> | Run, debug, or download the target remotely. Common values are draft, latest, or a specific version number. |
--entrypoint <id> | Select the Workflow entry for the remote run or debug-node; when omitted, use the target version default entry. Conversation does not accept non-null values. |
--release-log <text> | Publish the log. For automatic publish after upload, or for publish. |
--source-mode <bundled|source> | Version source mode. Default bundled; when set to source, the original source code snapshot is retained. |
--server-runtime / --no-server-runtime | Explicitly enable or disable the version's Server runtime for upload / publish; the flags are mutually exclusive. |
--desktop-platform <macos|windows> | Add a Desktop download target for upload / publish; repeatable and forces source mode. |
--path <path> | Local workflow directory or download destination directory. |
--file <archive> | The .tgz workflow package already exists. |
--output <file.tgz> | pack The path of the generated compressed package. |
--no-wait | upload Returns task information immediately after creating a server preparation task, without polling for completion status. |
--create | For upload, create or reuse the remote project with the UUID already declared in local package.json.id, and submit the current projectInfo. Server never assigns or writes back the UUID. |
Configuration and Login
| Source | Description |
|---|---|
Current Project .env | Read from the working directory where the command is executed. |
Monorepo root .env | Reads additional data only when running within the source code repository. |
| CLI Login state file | login writes to workflow-auth.json, and subsequent commands can be reused. |
| Environment variable | Explicit environment variables take precedence over .env. |
.env Example:
WORKFLOW_SERVER_URL=http://localhost:7125
WORKFLOW_SERVER_ADMIN_KEY=replace-with-admin-key
WORKFLOW_REPO_ROOT=/absolute/path/to/workflow-code
WORKFLOW_WORKSPACE_PACKS_DIR=/absolute/path/to/writable/workflow-packs
Configure Priority
| Configuration item | Priority |
|---|---|
| server URL | --server > WORKFLOW_SERVER_URL > CLI login status> http://localhost:7125 |
| token | --token > WORKFLOW_SERVER_ADMIN_KEY > CLI login status |
| repo root | WORKFLOW_REPO_ROOT> Find the root directory of the project containing pnpm-workspace.yaml from the current directory or the CLI file location up |
| pack temporary directory | WORKFLOW_WORKSPACE_PACKS_DIR > <repo root>/workspace/.packs |
| CLI Login state directory | WORKFLOW_CLI_AUTH_DIR> System default application configuration directory |
The CLI login state file is namedworkflow-auth.json. The default directory for macOS is~/Library/Application Support/workflow-code,Windows defaults to%APPDATA%/workflow-code, and Linux defaults to$XDG_CONFIG_HOME/workflow-codeor~/.config/workflow-code.
When Publish runs from the packaged Desktop, the Desktop sets WORKFLOW_WORKSPACE_PACKS_DIR to a writable location under its user data directory. In addition, upload --path <workflow-dir> resolves local workflow dependencies such as ../sibling-workflow relative to the parent of <workflow-dir>, preventing the packaged Desktop from treating app.asar as the project root.
Command List
| Command | Description |
|---|---|
login | Log in by browser device flow and save the CLI dedicated connection configuration. |
logout | Empty the saved connection configuration. |
status | Check to see if you are currently logged in. |
health | Request server /health. |
pack | Make the local project .tgz. |
upload | Upload the project package; automatic publishing is optional. |
publish | Publish a remote draft as a new version. |
versions | View the workflow version list. |
run | Run Workflow/Conversation remotely; Kanban will be explicitly denied. |
debug-node | Remotely runs a single debug node in the Workflow/Conversation registry. |
download | Download remote files to the local project directory; Kanban binary resources will be restored to their original byte sequences. |
help | Output help information. |
Output and exit codes
| Situation | Behavior |
|---|---|
server returns errCode: 0 | Output JSON, the exit code remains successful. |
The server returned a non-zero errCode | Output JSON and set the exit code to 1. |
| Missing parameters or local command failed | Output error message with exit code 1. |
Full Release Example
pnpm exec workflow-code workspace health --server http://localhost:7125
pnpm exec workflow-code workspace login --server http://localhost:7125
pnpm exec workflow-code workspace pack hello
pnpm exec workflow-code workspace upload hello --create --release-log "Initial release" --server-runtime --source-mode bundled
pnpm exec workflow-code workspace versions hello
pnpm exec workflow-code workspace run hello --target latest --entrypoint main -- --message "hello"
You can continue to use the local development address when running from the source code; replace the deployment environment with your server address. For example:
workflow-code workspace health --server http://localhost:7130
workflow-code workspace login --server http://localhost:7130
The workspace CLI uses the top-level package.json.id UUID as the remote project identifier for upload, publish, run, and download operations. The <workflow> positional argument can be a local directory name or workflow name; the CLI first reads package.json.id from that directory. Passing a UUID directly skips the local package lookup. A missing or invalid local UUID must be fixed in source first. If the UUID is valid but the server project does not exist, use workspace upload <workflow> --create to create that exact UUID.
Release targets are immutable version metadata, not project display platforms. With no target flags, a first Workflow/Conversation upload defaults to Server only and later uploads inherit the previous exact version on Server; Kanban always disables Server. A direct publish with only --desktop-platform first reads the remote project type so Kanban is not incorrectly marked Server-runnable. Automatic upload-and-publish reuses the same target object for package preparation and publication.
When Workflow/Conversation source code references other workspace workflow through ../<sibling-workflow>/...,pack and upload will also enter these sibling workflow source codes into the workspace/workflow/* structure in the archive to ensure that the server side can resolve local dependencies when building draft/runtime packages without manual packaging. Kanban With the configured artifactDir and HTML entry as static site boundaries, no README or executor is required; the server does not run front-end builds.
All local packaging only reads .workflowignore in each project’s root directory and does not read .gitignore. The absence of a valid rule will prompt the number and total size of all common files;.workflowignore itself, project entry, and necessary metadata cannot be excluded. The product catalogs for Kanban and dist are not automatically retained or excluded by the host; they must be explicitly selected by the project rules.
Codex manual upload example
The local Codex project can be packaged as .tgz first, and then uploaded to the existing package through upload --file, which is suitable for scenarios that require manual confirmation of archived content or reuse of package files:
pnpm exec workflow-code workspace pack codex --path ./codex-project --output ./workspace/.packs/codex-manual.tgz
pnpm exec workflow-code workspace upload codex --file ./workspace/.packs/codex-manual.tgz
pnpm exec workflow-code workspace publish codex --release-log "manual codex upload"