# swarmops sync status

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

Show how main and a git remote's followed branch stand, as the last fetch saw it.

Offline: it reads the store and its mirror only, takes no lock and runs no git. A branch never fetched gives fetched false.

```yaml
title: "swarmops sync status"
description: "Show how main and a git remote's followed branch stand, as the last fetch saw it."
group: "remotes"
since: "0.2.0"
mutates: false
identity_required: false
mcp_tool: "sync_status"
envelope_op: "sync_status"
exit_codes: [0]
errors: []
syntax: "swarmops sync status [OPTIONS] <REMOTE>"
```

## Syntax

```text
swarmops sync status [OPTIONS] <REMOTE>
```

## Required arguments

### `REMOTE`

Syntax: `<REMOTE>`.

The remote, by its name.

## Optional arguments

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

### `--limit`

Syntax: `-n, --limit <N>`.
Default: `50`.

The most unpublished changesets to list.

## Examples

### CLI

No recorded example yet.

### MCP

No recorded example yet.

## Return information

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ahead` | `integer` | yes | How many changes on `main` are above the base: unpublished. |
| `base` | `string or null` | no | The newest changeset on `main`'s first-parent chain that the remote's head reaches; omitted when there is none. |
| `behind` | `integer` | yes | How many changesets on the remote's first-parent chain are above the base. |
| `branch` | `string` | yes | The followed branch. |
| `fetched` | `boolean` | yes | Whether a fetch ever saw the followed branch. |
| `remote` | `string` | yes | The remote, by its name. |
| `remote_head` | `RemoteHead or null` | no | The followed branch's head as the last fetch saw it; omitted when none did. |
| `truncated` | `boolean` | yes | Whether a count or the list stopped at its bound. |
| `unpublished` | `array of ChangesetSummary` | yes | The unpublished changes, newest first, at most `limit`. |

Envelope `op`: `sync_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 clone`](clone.md)
- [`swarmops remote add`](remote-add.md)
- [`swarmops remote remove`](remote-remove.md)
- [`swarmops remote list`](remote-list.md)
- [`swarmops fetch`](fetch.md)
- [`swarmops push`](push.md)
- [`swarmops sync`](sync.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)