Server Workspace CLI
steamharness workspace, provided by @steamharness/cli, manages Server storage for Workflow, Conversation and Kanban projects. Use top-level steamharness run/json for local execution. Server never loads or executes uploaded project code.
Commands
| Command | Purpose |
|---|---|
| login, logout, status | Sign in, sign out and inspect connection status. |
| health | Check Server health. |
| pack | Package files using .steamharnessignore. |
| upload | Upload source or a project group; optionally publish. |
preparation | Read file processing progress and failures. |
| publish | Save an immutable source version and update latest. |
| versions | Read history, release notes and source hashes. |
| download | Download a published project or group. |
file-upload, file-download, file-delete | Manage independent business files. |
| help | Show help. |
Options
| Option | Purpose |
|---|---|
--server <url> | Overrides STEAMHARNESS_SERVER_URL, saved connection and channel default (dev: http://localhost:7126). |
--token <token> | Overrides STEAMHARNESS_SERVER_ADMIN_KEY and saved credentials. |
--target <version> | Exact download version or latest; draft is rejected. |
--release-log <text> | Release notes; upload publishes automatically when supplied. |
--path <directory> | Local project or download directory. |
--file <path> | Existing archive or business file. |
--mime-type <type> | Explicit business file MIME. |
--output <path> | Archive or file download path. |
--no-wait | Return the stored archive's processing job without polling. |
--create | Create or reuse the project using local package.json.id. |
--project-group, --dependency <alias=path> | Package, upload or download a group. |
--deployment <id>, --publish-group | Query or publish a group processing job. |
Unknown options fail. Declare static type in package.json.steamHarness.projectType; the uploaded package.json.version determines the version. Published versions cannot be overwritten. Server only extracts, validates and stores files, without installing dependencies or building. Prepare Kanban static assets locally.
Upload and Download
steamharness workspace login --server http://localhost:7126
steamharness workspace upload hello --create --release-log "Initial release"
steamharness workspace versions hello
steamharness workspace download hello --target latest --path ./downloaded-hello
The project argument accepts a UUID, name or local directory. CLI prefers the directory's stable package.json.id. Packaging uses each root's .steamharnessignore, ignoring .gitignore; required entries and the rules file cannot be excluded. Included dependencies lock exact versions and source hashes. Downloads check each project's source permission and report skip reasons and request links. Downloads have no operating system restriction.
Business Files
steamharness workspace file-upload <project UUID> --file ./map.png
steamharness workspace file-download <file ID> --output ./verified-map.png
steamharness workspace file-delete <file ID>
Upload accepts ordinary files up to 50 MiB and returns a FileReference with storage: "server". Writes require project data write access; reads require project access. Downloads require a new path and never overwrite files; HTTP failures create no local file. Store references in KV rather than image base64.
Credentials and Output
CLI reads .env from the current directory and source repository root; existing process variables take priority. Credentials use workflow-auth.json in the operating system application configuration directory, overridable with STEAMHARNESS_CLI_AUTH_DIR.
Success returns { errCode: 0, errMessage: "", data }; server and local argument errors produce a nonzero exit code. Processing jobs retain progress and failure details. Failed uploads preserve published snapshots.
Use --group-id <id> when creating or first uploading into a group with developer access. Omit it to own a personal project. Upload, publication and Server writes require developer access; published downloads and data reads require guest access. Cookies and API keys both use current project and group memberships.
Without an explicit Server, the client uses its build channel: http://localhost:7126 for dev and the corresponding site for alpha or main. Set STEAMHARNESS_SERVICE_CHANNEL=dev|alpha|main to select the default channel explicitly; --server, STEAMHARNESS_SERVER_URL and saved connections retain higher priority.