# swarmops ws create

> Release: 0.11.0 · Last changed: 2026-11-08 · Source: https://github.com/KeiaiLab/SwarmOps/blob/stable/docs/reference/commands/ws-create.md

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.

```yaml
title: "swarmops ws create"
description: "Make a workspace NAME in a directory of its own, and bootstrap it."
group: "workspaces"
since: "0.3.0"
mutates: true
identity_required: true
mcp_tool: "ws_create"
envelope_op: "ws_create"
exit_codes: [0, 1]
errors: [E_WS_EXISTS, E_PATH_NOT_EMPTY, E_WS_UNPORTABLE]
syntax: "swarmops ws create [OPTIONS] <NAME>"
```

## Syntax

```text
swarmops ws create [OPTIONS] <NAME>
```

## Required arguments

### `NAME`

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](../cli.md#global-options).

### `--path`

Syntax: `--path <DIR>`.

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

### `--base`

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

The changeset or ref whose tree it holds.

### `--prefix`

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.

### `--all`

Syntax: `--all`.

Write out the whole tree.

### `--from`

Syntax: `--from <DIR>`.

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

### `--status-after`

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

### CLI

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

```json
{
  "ok": true,
  "op": "ws_create",
  "api": 1,
  "result": {
    "name": "w1",
    "path": "[tmp]/w1",
    "base": "[c1]",
    "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.

### MCP

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`](../errors.md#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`](../errors.md#e_path_not_empty) (exit 1): `ws create` was given a directory that holds something already (`details.path`).
- [`E_WS_UNPORTABLE`](../errors.md#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`](../errors.md#e_not_a_repo), [`E_IO`](../errors.md#e_io) or [`E_STORE_CORRUPT`](../errors.md#e_store_corrupt); a command line the grammar refuses is [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2).

## See also

- [`swarmops ws status`](ws-status.md)
- [`swarmops ws diff`](ws-diff.md)
- [`swarmops ws commit`](ws-commit.md)
- [`swarmops ws rebase`](ws-rebase.md)
- [`swarmops ws resolve`](ws-resolve.md)
- [`swarmops ws land`](ws-land.md)
- [`swarmops ws materialize`](ws-materialize.md)
- [`swarmops ws discard`](ws-discard.md)
- [`swarmops ws snapshot`](ws-snapshot.md)
- [`swarmops ws list`](ws-list.md)
- [`swarmops ws info`](ws-info.md)
- [`swarmops ws delete`](ws-delete.md)
- [`swarmops ws hook`](ws-hook.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)