# swarmops ws delete

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

Remove a workspace's directory, then its entry.

Edits or commits not landed are E\_WS\_DIRTY without --force (delete anyway) or --rescue (commit the edits as a rescue changeset first).

```yaml
title: "swarmops ws delete"
description: "Remove a workspace's directory, then its entry."
group: "workspaces"
since: "0.3.0"
mutates: true
identity_required: false
mcp_tool: ""
envelope_op: "ws_delete"
exit_codes: [0, 1]
errors: [E_WS_DIRTY]
syntax: "swarmops ws delete [OPTIONS] <NAME>"
```

## Syntax

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

## Required arguments

### `NAME`

Syntax: `<NAME>`.

The workspace, by name.

## Optional arguments

The command also takes the [global options](../cli.md#global-options).

### `--force`

Syntax: `--force`.

Delete it even with edits or unlanded commits.

### `--rescue`

Syntax: `--rescue`.

Commit its edits as a rescue changeset first.

## Examples

### CLI

```sh
swarmops --repo [tmp]/store --as agent/worker-17 ws delete w1
```

```json
{
  "ok": false,
  "op": "ws_delete",
  "api": 1,
  "error": {
    "code": "E_WS_DIRTY",
    "message": "the workspace holds edits this would overwrite: [\"src/lib.rs\"]",
    "retryable": false,
    "exit": 1,
    "details": {
      "paths": [
        "src/lib.rs"
      ]
    },
    "hint": "swarmops ws commit -m <message>, or swarmops ws delete w1 --rescue"
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {
      "[c1]": "[c1]"
    },
    "auth": "trust"
  }
}
```

Exit code 1. 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.

## Return information

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | `string` | yes | The workspace's name. |
| `head` | `string` | yes | Its head when it was deleted. |
| `rescued` | `string or null` | no | The rescue changeset of its edits, when there were some. |

Envelope `op`: `ws_delete`.

Exit codes:

- `0`: Success.
- `1`: The operation failed.

## Errors

- [`E_WS_DIRTY`](../errors.md#e_ws_dirty) (exit 1): The workspace holds edits the operation would overwrite or lose (`details.paths`, the first 20); the hint names the command that commits or discards 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 create`](ws-create.md)
- [`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 hook`](ws-hook.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)