swarmops ws create#

Describes v0.11.0Last changed 2026-11-08View as Markdown

Make a workspace NAME in a directory of its own, and bootstrap it.

The directory holds the tree of --base under the --prefix paths, with the .gitignore and .swarmignore files of the directories above them (--all, or neither: the whole tree), and .swarmws/, its private state. The same command again is the same workspace (created: false). A new workspace gets the files .worktreeinclude lists from --from, and runs the repository's bootstrap command (.swarmops/workspaces.json) unless SWARMOPS_WS_BOOTSTRAP=skip. It needs an identity.

Metadata

Group: workspaces
Since: 0.3.0
Mutates: yes
Identity required: yes
MCP tool: ws_create
Envelope op: ws_create
Exit codes: 01
Errors: E_WS_EXISTS E_PATH_NOT_EMPTY E_WS_UNPORTABLE

Syntax#

Syntax

swarmops ws create [OPTIONS] <NAME>

Required arguments#

Syntax: <NAME>.

The workspace's name: 1 to 64 of a-z, 0-9, ., _ and -, not starting with ..

Optional arguments#

The command also takes the global options.

Syntax: --path <DIR>.

The directory to make it in (default: NAME in the working directory).

Syntax: --base <REV>. Default: main.

The changeset or ref whose tree it holds.

Syntax: --prefix <P>....

A repository path whose subtree to write out, with the .gitignore and .swarmignore files of the directories above it; give it again for more.

Syntax: --all.

Write out the whole tree.

Syntax: --from <DIR>.

A directory whose .worktreeinclude names files to copy in (default: none).

Syntax: --status-after <STATUS_AFTER>. Default: page.

page: the first page of the status follows the result; none: it is left out. Values: page: The first page of the status; none: No status.

Examples#

Shell

swarmops --repo [tmp]/store --as agent/worker-17 ws create w1 --path [tmp]/w1 --prefix src

Output

{ "ok": true, "op": "ws_create", "api": 1, "result": { "name": "w1", "path": "[tmp]/w1", "base": "[c1]",

Show 26 more lines

"head": "[c1]", "prefixes": [ "src" ], "created": true, "status_after": { "name": "w1", "base": "[c1]", "head": "[c1]", "main": "[c1]", "behind_by": 0, "state": "clean", "changes": [], "truncated": false } }, "meta": { "repo": "[tmp]/store", "elapsed_ms": "[elapsed_ms]", "resolved": { "[c1]": "[c1]", "main": "[c1]" }, "auth": "trust" } }

Exit code 0. Recorded by the CLI tests. A name in square brackets, such as [tmp] or [c1], stands for what differs from run to run: the test's temporary directory, an id, a time.

No recorded example yet.

Return information#

result is a WsInfo (swarmops schema WsInfo prints its JSON Schema).

Field	Type	Required	Description
`all`	`boolean`	no	Whether the whole tree is written out.
`base`	`string`	yes	The target's changeset its chain starts from.
`created`	`boolean`	no	Whether this request made it: false for one that existed.
`head`	`string`	yes	Its chain's last changeset; `base` when nothing is committed.
`name`	`string`	yes	Its name.
`orphan`	`boolean`	no	Whether its directory is gone while its entry stays (`ws_list` with `check`).
`path`	`string`	yes	Its directory on the caller's host.
`prefixes`	`array of string`	no	The repository paths written out.
`snapshot`	`string or null`	no	Its latest snapshot (`ws_snapshot`, or an update's), on whichever head it was taken; `ws_info` only, omitted when there is none.
`status_after`	`WsStatus or null`	no	The status after the mutation; omitted when the request said `none`.

Envelope op: ws_create.

Exit codes:

0: Success.
1: The operation failed.

Errors#

E_WS_EXISTS (exit 1): ws create found a workspace of that name already, made by other arguments (details.name, details.path of the existing one).
E_PATH_NOT_EMPTY (exit 1): ws create was given a directory that holds something already (details.path).
E_WS_UNPORTABLE (exit 1): The tree holds paths the workspace's volume cannot hold: details.reason says why (case_collision, windows_name, reserved_name: a path component named .swarmws at any depth, in any ASCII case) and details.paths names them.

Any command that opens a store may also fail with a store error, such as E_NOT_A_REPO, E_IO or E_STORE_CORRUPT; a command line the grammar refuses is E_INVALID_ARG (exit 2).