# swarmops ws land

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

Land a workspace's chain on its target; with --check, rebase, check and land the checked tree.

Without --check the chain lands as it is (--mode merge). With it the workspace is rebased onto the target, the command runs in the workspace (the ARGV after --, else the repository's check in .swarmops/workspaces.json), and only the tree it ran on is published (--mode exact); a target that moved means rebase and check again, up to --max-attempts. --mode exact without --check publishes the tree of the last ws rebase.

```yaml
title: "swarmops ws land"
description: "Land a workspace's chain on its target; with --check, rebase, check and land the checked tree."
group: "workspaces"
since: "0.3.0"
mutates: true
identity_required: false
mcp_tool: "ws_land"
envelope_op: "ws_land"
exit_codes: [0, 1, 2]
errors: [E_INVALID_ARG, E_WS_STALE, E_CHECK_FAILED]
syntax: "swarmops ws land [OPTIONS] [-- <ARGV>...]"
```

## Syntax

```text
swarmops ws land [OPTIONS] [-- <ARGV>...]
```

## Required arguments

None.

## Optional arguments

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

### `--ws`

Syntax: `--ws <NAME>`.

The workspace, by its name in the store's registry (default: the one around the working directory).

### `--ws-path`

Syntax: `--ws-path <DIR>`.

The workspace's directory.

### `--message`

Syntax: `-m, --message <MSG>`.

The landed changeset's message, and the message to commit edits with first.

### `--key`

Syntax: `--key <KEY>`.

Makes a retry of this land safe: 1 to 64 letters, digits and '-', such as a uuid v7. Make a new one for each change you land, and give it again only to retry that land.

A land with a key first looks down the ref's first parents, to the change's base, for a changeset landed with the same key: one squashed from this HEAD is the land made before, which the land replays (status: replayed) without writing anything; one from another head is E\_INVALID\_ARG. A key not found there is looked for on the other main, release and branch refs: one that landed on another target is E\_INVALID\_ARG too, and details.target names the ref. Without a key, the same land run again finds its change on the ref already: E\_NOTHING\_TO\_LAND.

### `--target`

Syntax: `--target <REF>`.

The ref to land on (default: the workspace's target).

### `--check`

Syntax: `--check`.

Run a check on the rebased tree before it lands.

### `--check-timeout`

Syntax: `--check-timeout <S>`.
Default: `900`.

The most seconds the check runs before it is killed.

### `--mode`

Syntax: `--mode <MODE>`.

merge or exact (default: exact with --check, else merge). Values: `merge`: Merge onto the target's head, wherever it has moved; `exact`: Publish only the tree the workspace was rebased to.

### `--max-attempts`

Syntax: `--max-attempts <N>`.
Default: `8`.

How many times to rebase, check and land before E\_CAS\_RETRY\_EXHAUSTED: 1 to 32.

### `ARGV`

Syntax: `<ARGV>`.

The check's command and arguments, after --.

### `--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 land --ws w3 --mode exact
```

```json
{
  "ok": false,
  "op": "ws_land",
  "api": 1,
  "error": {
    "code": "E_INVALID_ARG",
    "message": "an exact land needs the workspace rebased onto its target since its last commit",
    "retryable": false,
    "exit": 2,
    "details": {
      "missing": "rebase"
    },
    "hint": "swarmops ws rebase, check the workspace, then swarmops ws land --mode exact"
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {
      "[c1]": "[c1]",
      "[id13]": "[id13]",
      "main": "[c1]"
    },
    "auth": "trust"
  }
}
```

Exit code 2. 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 `WsLandResp` (`swarmops schema WsLandResp` prints its JSON Schema).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempts` | `integer` | yes | How many rebase, check and land attempts it took. |
| `land` | `LandResp` | yes | The store's land. |
| `status_after` | `WsStatus or null` | no | The status after the mutation; omitted when the request said `none`. |

Envelope `op`: `ws_land`.

Exit codes:

- `0`: Success.
- `1`: The operation failed.
- `2`: The request or the command line is malformed.

## Errors

- [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2): A malformed argument or request, including a command-line usage error.
- [`E_WS_STALE`](../errors.md#e_ws_stale) (exit 1): `ws status`, `ws diff`, `ws commit`, `ws materialize`, `ws land` (onto any target) or `ws rebase --continue` found the workspace's base gone from its target's history (`details.target`, `base`, `head`; `base_op`, the operation that moved the target to the base; `moved_op`, the latest that moved it to `head`, or null when not found).
- [`E_CHECK_FAILED`](../errors.md#e_check_failed) (exit 1): A workspace's check or bootstrap command failed or ran past its time (`details.stage`: `check` or `bootstrap`; `exit_code`, `timed_out`, the tails of its output, `log`, `changeset`).

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 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)