workspace download
workspace download retrieves the selected project source from Workflow Server and writes it to a local directory. draft uses the single-project file endpoint and replaces the destination directory. For a published version, the CLI sends the Desktop platform that matches the current operating system, reads the root version's dependency lock, and writes permitted included projects beside the root project. Downloads restore the source snapshot saved by Server without reapplying .workflowignore or .gitignore.
Kanban pictures, fonts and other binary resources in base64 file response transmission,CLI will decode and restore the original bytes; Text items still use the original string content.
Command Format
pnpm exec workflow-code workspace download <workflow> [--target draft|latest|version] [--path <dir>]
Parameter
| Parameter | Description |
|---|---|
<workflow> | The remote workflow name. |
--target <target> | Download the target. Default latest. |
--path <dir> | Local destination directory. Defaults to workspace/workflow/<workflow>. |
Target
| Value | Description |
|---|---|
draft | Only the current draft of the root project is downloaded and the target directory is completely replaced. Dependency locks are not processed. |
latest | Default. On macOS or Windows, resolves to the newest online root version compatible with the current platform, then downloads from that exact version's dependency lock. This can differ from the overall latest version and the Server latest version. |
| Specific version number | Downloads the selected published version and its included dependencies without resolving dependency projects to their latest versions. The root version must support the current Desktop platform and use source mode. |
workspace download sends platform=macos on macOS and platform=windows on Windows. Linux and other operating systems have no implicit compatible platform, so the command rejects every target before downloading.
API
| Steps | Endpoint |
|---|---|
| Download draft | GET /api/workflows/{workflow}/files?target=draft&includeBinary=true |
| Download the released project group | GET /api/workflows/{workflow}/project-group-download?target=<target>&platform=macos|windows |
Writing Rules
| Rules | Description |
|---|---|
| draft target directory | Recursively clear before writing, and then restore the root project according to the server return path. |
| Published Root Project | Writes to the --path or default root directory; rejects overwrite if the directory is already occupied by another UUID. |
| included dependence | Write to a separate sibling directory at the same parent level as the root project. If the same UUID item already exists in the parent directory, it is considered satisfied and not overwritten. |
| Write Content | Text is written directly to content;encoding: "base64" strictly decoded before writing binary content. |
| Atomicity | The new project is first written into the temporary staging of the same parent directory. If any verification, directory move or write fails, the newly added directory is removed. |
Security verification
| Verification | Description |
|---|---|
| Absolute Path Disallowed | The server returns a /... or Windows drive letter path that is rejected. |
| Prohibit path traversal | Empty paths, ., .., or paths containing empty segments are rejected. |
| Reserved server list | dist, .workflowignore, or other uploaded files will be restored as they are, and will not be ignored for the second time. |
| Dependency-lock consistency | The mutually confirmed relatedProjects in the root Kanban's exact version must match the dependency lock returned by Server. CLI recomputes each returned project's SHA-256 from paths and original file bytes; the root version, every included project's exact version, and every source hash must match. |
| Desktop release compatibility | Server checks only the root version's executionTargets.desktop against the current platform. Included dependencies continue to follow the root version's exact dependency lock, retained-source state, and download permissions; they do not need to declare the current Desktop platform separately. |
| Host Data Isolation | Server responses and local writes reject .env*, KV, PersistentValue, scheduled schedule, run history, SQLite, workflow-auth.json, and other host user configurations. |
Output
| Situation | Output |
|---|---|
| Full Download | Output the root project, included dependencies, local paths, exact versions, and complete: true. |
| Partial download | The project with permission is still saved, and the external, source code is unavailable or the dependency and application link that requires permission are output in skippedDependencies. |
| Illegal file path | Output error message with exit code 1. |
| Not logged in | Output error message with exit code 1. |
Example
pnpm exec workflow-code workspace download hello
pnpm exec workflow-code workspace download hello --target latest
pnpm exec workflow-code workspace download hello --target 1.2.0 --path ./workspace/workflow/hello-copy
Precautions
| Scene | Recommendation |
|---|---|
| Target directory has local changes | Back up or select a new --path first. |
| Just want to see the remote version | Use versions. |
| included dependency missing permissions | Open the short-term application link in the output; Retry the same command after the source owner/manager approves, and the same UUID item will not be rewritten. |
| external dependence | Do not participate in the linkage download, you need to prepare the source project corresponding to UUID. |
| Current OS is not macOS or Windows | There is no implicit compatibility target. Download on a Desktop platform declared by the release instead. |
| No data for Kanban after download | is expected behavior. Server KV does not enter locally; please run the source Workflow sync entry locally. |