# swarmops ws status

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

What changed in a workspace against its head, and how far its target has moved.

```yaml
title: "swarmops ws status"
description: "What changed in a workspace against its head, and how far its target has moved."
group: "workspaces"
since: "0.3.0"
mutates: false
identity_required: false
mcp_tool: "ws_status"
envelope_op: "ws_status"
exit_codes: [0]
errors: []
syntax: "swarmops ws status [OPTIONS] [PATH]..."
```

## Syntax

```text
swarmops ws status [OPTIONS] [PATH]...
```

## 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.

### `PATH`

Syntax: `<PATH>`.

Only these repository paths, and what is below them.

### `--full`

Syntax: `--full`.

Hash every file instead of trusting unchanged stats.

### `--limit`

Syntax: `--limit <N>`.
Default: `500`.

The most changes to print.

### `--cursor`

Syntax: `--cursor <C>`.

Where the previous page stopped.

## Examples

### CLI

No recorded example yet.

### MCP

No recorded example yet.

## Return information

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `base` | `string` | yes | The target's changeset its chain starts from. |
| `behind_by` | `integer` | yes | How many changesets the target's first-parent history holds that `base`'s lacks: those past `base` when it is on that history; otherwise (a sync dropped it, or the target moved back) those before where the two histories meet, 0 when the target head is on `base`'s first-parent history fewer than 10,000 changesets behind `base`. At most 10,000. |
| `changes` | `array of WsChange` | yes | The changes, by path. |
| `cursor` | `string or null` | no | Where this page stopped. |
| `head` | `string` | yes | Its chain's last changeset. |
| `main` | `string` | yes | The head of the workspace's target ref (`main`, or `release/<name>`), read first. |
| `name` | `string` | yes | The workspace's name. |
| `outside` | `array of string` | no | A sparse workspace's topmost entries off its prefixes, in path order: edits `ws commit` and `ws land` refuse until `ws materialize` widens the prefixes. At most the first 1,000, on every page. |
| `outside_truncated` | `boolean` | no | Whether `outside` stopped at 1,000 entries. |
| `rebasing` | `WsRebasing or null` | no | The rebase in progress, when `state` is `rebasing`. |
| `state` | `WsState` | yes | Whether the workspace is rebasing. |
| `truncated` | `boolean` | yes | Whether more changes follow: give `cursor` to read them. |

Envelope `op`: `ws_status`.

Exit codes:

- `0`: Success.

## Errors

No golden step shows this command failing yet.

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