workspace upload
workspace upload sends a project package to Workflow Server. Without --file, it first packages local files according to .workflowignore; Server returns a preparation-job ID after receiving the archive. A Workflow/Conversation with Server runtime enabled installs dependencies and bundles or minifies. With Server disabled, preparation only unpacks, validates, and hashes source without installing dependencies or creating a runtime. Kanban always disables Server and only validates its artifact directory and HTML entry while retaining static resources. The CLI polls until completion by default. With --release-log, it publishes after preparation and reuses the same release policy.
CLI does not install or modify local project dependencies during packaging and uploading, and does not require the local presence of node_modules. When --file is not passed, only the source code is collected and the archive is generated, and the dependency installation is the responsibility of the server construction phase. The server will not write workflow-code, @workflow-code/cli only for platform API and development commands to version runtime; other business dependencies will be organized into portable archives without symbolic links.
Uploading files is controlled only by the project root .workflowignore;.gitignore does not participate. In the absence of a valid rule,CLI will prompt the number and total size of all common files to be uploaded before uploading. The actual Kanban artifactDir must be preserved; the front-end source, tests, dependencies, and secret are explicitly determined by the project rules.
Before uploading, the local workflow top level package.json.id is verified. This field must be UUID and represents the server-side project primary key;CLI no longer deduces the remote project ID from the directory name or package name.
If the current workflow source code references other workspace workflow through relative paths, such as ../openai-agents/index,CLI will put these sibling workflow source codes into the workspace/workflow/* directory of the archive during the local packaging phase to ensure that these local dependencies can be resolved when the server side is built.
Command Format
pnpm exec workflow-code workspace upload <workflow> [--path <workflow-dir>] [--file <archive>] [--release-log <text>] [--source-mode bundled|source] [--server-runtime|--no-server-runtime] [--desktop-platform macos|windows] [--no-wait] [--create] [--project-group] [--publish-group] [--dependency <alias>=<path>]
Parameter
| Parameter | Description |
|---|---|
<workflow> | Local workflow directory name, workflow name, or directly pass a remote project UUID. |
--path <workflow-dir> | package and upload the specified local directory. |
--file <archive> | Upload the existing .tgz package directly. |
--release-log <text> | Call the publish immediately after the upload succeeds. |
--source-mode <bundled|source> | Source mode for automatic publication. Defaults to bundled; source retains the original source snapshot. |
--server-runtime | Prepare a Server runtime for this version. |
--no-server-runtime | Disable this version's Server runtime; Workflow/Conversation still require at least one Desktop target. |
--desktop-platform <macos|windows> | Allow the matching Desktop download; repeatable, automatically requires source, and conflicts with --source-mode bundled. |
--no-wait | When a single project is uploaded, the server will return jobId immediately after the server preparation task is created, and the task completion status will not be polled. Cannot be used in combination with project groups or automatic releases within this command. |
--create | Create or reuse the Server project with the UUID and projectInfo already declared by the local package. A missing UUID or storage declaration fails immediately. |
--project-group | Create project-group v1 from the root Kanban's mutually confirmed related projects instead of uploading one project. |
--dependency <alias>=<path> | Package the local related project for an alias as an included dependency; repeatable. Unspecified confirmed relations remain external, while pending relations are excluded from the group. |
--publish-group | Publish immediately after the project group preparation is completed; it also takes effect when --release-log is not filled in. |
Authentication
| Configuration | Description |
|---|---|
| server URL | From the --server, WORKFLOW_SERVER_URL, or CLI login state. |
| token | From the --token, WORKFLOW_SERVER_ADMIN_KEY, or CLI login state API Key. |
| Not logged in | The command fails with a prompt to execute workspace login first. |
Upload mode
| Mode | Behavior |
|---|---|
| Default | The upload package is a remote draft. |
--file | Skips local packaging and reads the specified archive directly. |
--release-log | Call /api/workflows/{workflow}/publish after the upload is successful. |
| Release targets | The package request uses `serverRuntime=true |
--no-wait | Only used for single project upload, only return server preparation task; later by preparation API query status. The project team must wait for the entire team to complete permission verification, version reservation, and preparation. |
--create | Call POST /api/workflows with the package workflowId, derived projectType, and complete projectInfo to create or reuse the remote project before uploading the draft package. The local project ID is never modified. |
| Project group | Using --project-group, --dependency, or --publish-group enters project-group mode. CLI verifies that the root project is a Kanban and resolves included/external projects from mutually confirmed aliases in projectInfo.relatedProjects. |
The empty project created by --create stores the projectType derived from current source and the package's current projectInfo; the first upload must match them. Workflow/Conversation types come from the executor, and Kanban types come from package.json.workflowCode.projectType. Once the remote project has a draft or version, later uploads update derived metadata from the new explicit declarations. Upload never guesses a type from a directory or package name.
Project group upload
Project-group mode first creates or reuses Server projects for the root Kanban and every included related project, then packages each project according to its own .workflowignore into a tar.gz containing project-group.json and the project archives. Server validates all project permissions and reciprocal declarations atomically before reserving versions. Dependencies publish first; the root Kanban activates last and stores an exact dependency lock. Included projects are always published in source mode so authorized downloaders can obtain their source. Do not pass --dependency when that source cannot be distributed. KV read and write permissions come only from both projects' current projectInfo; CLI does not create a separate data grant.
CLI rejects .env*, KV, PersistentValue, scheduled schedule, run history, SQLite, workflow-auth.json, and other host user configurations in each project archive and outer project group. Local KV does not enter Server; data must be initialized on the Server side via source Workflow entrypoint, Server Run API, or business interface after publishing.
API
| Steps | Endpoint |
|---|---|
| Upload Package | POST /api/workflows/{workflow}/package?serverRuntime=<boolean>&desktopPlatform=<platform> |
| Query preparation task | GET /api/workflows/{workflow}/preparations/{jobId} |
| Auto Publish | POST /api/workflows/{workflow}/publish |
| Create a project group plan | POST /api/deployments |
| Upload Project Group | POST /api/deployments/{deploymentId}/package |
| Release Project Team | POST /api/deployments/{deploymentId}/publish |
You can also use workflow-code workspace preparation <workflow-id> <job-id> to query the preparation tasks that have been returned; the command does not cancel or restart the server tasks.
Output
| Situation | Output |
|---|---|
| Upload Only | After the preparation is successful, output the draft build result JSON. |
| Upload and Publish | After the preparation is successful, output the build result, and then output the publish JSON. |
| Project team | Output the deployment record, which contains the reserved version, preparation phase, precise release version, and failure reason for each project. |
The server returned a non-zero errCode | Output JSON, exit code is 1. |
Example
pnpm exec workflow-code workspace upload hello --create
pnpm exec workflow-code workspace upload hello --path ./workspace/workflow/hello
pnpm exec workflow-code workspace upload hello --file ./workspace/.packs/hello.tgz
pnpm exec workflow-code workspace upload hello --create --release-log "Initial release" --server-runtime
pnpm exec workflow-code workspace upload hello --release-log "macOS local release" --no-server-runtime --desktop-platform macos
pnpm exec workflow-code workspace upload hello --release-log "Cloud and both desktops" --server-runtime --desktop-platform macos --desktop-platform windows
pnpm exec workflow-code workspace upload stock-kanban \
--path ./stock-kanban \
--dependency stocks=./stock-workflow \
--publish-group \
--release-log "Publish the market board project group"
The Codex sample can also be packaged manually before uploading the existing archive:
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"
Samples with third-party SDKs also declare their own package.json dependencies in the workflow directory.
For example, workspace/workflow/openai-agents declares @openai/agents, openai
and zod,workspace/workflow/claude-agent declaration
__WC_INLINE_000 , WC_INLINE_001__declaration
__WC_INLINE_000 , WC_INLINE_001__declaration
@earendil-works/pi-coding-agent;server runtime installs these business dependencies when building the runtime package.
OPENAI_API_KEY / OPENAI_BASE_URL for the OpenAI sample, for the Claude Agent sample
ANTHROPIC_API_KEY, ANTHROPIC_* / OPENAI_* provider Configuration for Pi Agent Sample
are configured through the server environment variables page. The OpenAI, Claude Agent, and Pi Agent samples all include
knowledge_documents tools; these workflow tools are used in server runtime
server/database-backed PersistentValue stores the project knowledge document. Local CLI/Desktop run
At the same workflow, you can use the independent byWORKFLOW_PERSISTENT_VALUE_STORE_DIR.
The local repository is not automatically synchronized with the server project.
The custom openai-agents test_tool is packaged with the source code and used to initiate small
HTTP GET/POST test request and return response summary; optional local shellTool runner also comes with source code
packaging, which when enabled through --local-shell is still restricted by the --workdir and workflow command policies.
Precautions
| Scene | Description |
|---|---|
| Sensitive files in the package | The host does not implicitly exclude .env, node_modules, or Git metadata; it must be explicitly configured in .workflowignore. |
| Git and upload | .gitignore does not participate in the upload; the same dist can not commit Git but still be retained and uploaded by .workflowignore. |
| Kanban Static resources | Within artifactDir HTML, CSS, JavaScript, images, and fonts are preserved in the original bytes; pages must comply with relative paths within the product directory and offline sandbox. |
| Project Team Data | The project team only delivers the source code and does not upload local KV, schedule, run history, environment variables, or user configuration; the Desktop and Server data remains isolated from each other. |
| Interrupt Wait | A CLI exit or network interruption does not cancel the server preparation task, after which you can use the preparation to query the API recovery status. |
| Automatic publishing failed | the upload may have been successful. if the publish fails, you need to continue troubleshooting based on the output. |
| Large SDK First Installation | The server retains the lockfile in the package and installs the determined version as lockfile. The SDK that contains the platform binary may take a long time to upload for the first time. When the download time out, check the npm registry network, disk space, and dependent installation timeout configuration of the server. |
| UUID missing or invalid | CLI fails and requires the top-level package.json.id to be fixed first. --create never assigns, converts, or writes back a UUID. |
| 403 permission error | CLI will give priority to prompt "no project permission" or "has been banned from running/uploading", and will not uniformly guide the login again. |