# sync

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

Fetches a git remote, lands main's unpublished changes onto its head (those the remote holds already are dropped), moves main there and pushes it; with mode local it pushes nothing. A conflict is E\_CONFLICT with the report a land gives, and nothing moves.

```yaml
title: "sync"
description: "Sync with a git remote."
since: "0.2.0"
mutates: true
identity_required: true
cli_command: "swarmops sync"
envelope_op: "sync"
request_type: "SyncReq"
annotations: {"destructiveHint":false,"idempotentHint":false,"openWorldHint":true,"readOnlyHint":false}
max_result_chars: null
```

## Input schema

`arguments` is a `SyncReq`: `swarmops schema SyncReq` prints the type. A field the type does not know is ignored.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `max_attempts` | integer | no | `8` | How many times to fetch and land again when the remote or `main` moved meanwhile: 1 to 32. |
| `mode` | string | no | `"publish"` | `publish` (the default) pushes; `local` stops before the push. Whether `sync` sends what it landed. |
| `remote` | string | yes |  | The remote, by its name. |

### JSON Schema

As `tools/list` gives it: each `$ref` replaced by its definition, so that it stands alone.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "`sync`: fetch a remote, land `main`'s unpublished changes onto the remote's head, move\n`main` there and push it. It moves `main`, so it needs an identity.",
  "properties": {
    "max_attempts": {
      "default": 8,
      "description": "How many times to fetch and land again when the remote or `main` moved meanwhile: 1 to\n32.",
      "format": "uint32",
      "maximum": 32,
      "minimum": 1,
      "type": "integer"
    },
    "mode": {
      "default": "publish",
      "description": "`publish` (the default) pushes; `local` stops before the push. Whether `sync` sends what it landed.",
      "oneOf": [
        {
          "const": "publish",
          "description": "Land onto the remote's head, move `main`, and push it.",
          "type": "string"
        },
        {
          "const": "local",
          "description": "The same without the push: for a branch that takes pull requests only.",
          "type": "string"
        }
      ]
    },
    "remote": {
      "description": "The remote, by its name.",
      "type": "string"
    }
  },
  "required": [
    "remote"
  ],
  "title": "SyncReq",
  "type": "object"
}
```

## Annotations

It lands main's unpublished changes onto a git remote's head, moves main there and pushes. Run again after the remote moved, it lands again. It reaches the remote, beyond the store.

| Annotation | Value | Meaning |
| --- | --- | --- |
| `destructiveHint` | `false` | True: a tool that changes the store may overwrite or delete what is there, not only add to it. |
| `idempotentHint` | `false` | True: calling it again with the same arguments changes nothing more. |
| `openWorldHint` | `true` | True: it reaches beyond a closed set of things. Every tool here stays inside the store. |
| `readOnlyHint` | `false` | True: the tool does not change its environment, the store. |

Its entry in `tools/list` carries no `_meta`.

## CLI command

[`swarmops sync`](../commands/sync.md) runs the same operation and prints the same envelope.

## Examples

### MCP

No recorded example yet.

## Return information

A tool result: the envelope, whose `op` is `sync`, as `structuredContent` and again as the text of its one `content` block. `isError` is true exactly when the envelope's `ok` is false. On success the envelope's `result` is what [`swarmops sync`](../commands/sync.md#return-information) returns.

## Errors

A failed call is a tool result with `isError: true`; the envelope's `error.code` is one of the [error codes](../errors.md).

- [`E_INVALID_ARG`](../errors.md#e_invalid_arg): arguments that do not fit `SyncReq`, a field named twice among them included, or that break one of the server's own rules.
- [`E_IDENTITY_REQUIRED`](../errors.md#e_identity_required): the server runs with no identity.
- [`E_NOT_A_REPO`](../errors.md#e_not_a_repo): the server's store is not there; the server serves on.
- [`E_INTERNAL`](../errors.md#e_internal): the operation panicked, a bug.

Then the errors of the operation, as [`swarmops sync`](../commands/sync.md#errors) lists them.

## See also

- [`swarmops sync`](../commands/sync.md)
- [MCP tools](README.md)
- [MCP integration](../../develop/mcp.md)
- [Error codes](../errors.md)