# swarmops ref txn

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

Move several refs as one operation, each by compare-and-swap: all of them or none.

Each --move is NAME=EXPECT:TO: EXPECT the full id NAME names now, or new to create it; TO the revision to point it at, or delete. Every expectation is checked under the store's lock before any ref moves: one or more stale ones are E\_CAS\_MISMATCH, each listed in details.mismatches, and nothing is written. Each move follows ref set's and ref delete's rules. op undo of the operation restores every ref at once.

```yaml
title: "swarmops ref txn"
description: "Move several refs as one operation, each by compare-and-swap: all of them or none."
group: "refs"
since: "0.11.0"
mutates: true
identity_required: true
mcp_tool: "ref_txn"
envelope_op: "ref_txn"
exit_codes: [0]
errors: []
syntax: "swarmops ref txn [OPTIONS] --move <NAME=EXPECT:TO>"
```

## Syntax

```text
swarmops ref txn [OPTIONS] --move <NAME=EXPECT:TO>
```

## Required arguments

### `--move`

Syntax: `--move <NAME=EXPECT:TO>...`.

One move, NAME=EXPECT:TO, such as release/1=new:main; 1 to 64, each ref once.

## Optional arguments

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

## Examples

### CLI

No recorded example yet.

### MCP

No recorded example yet.

## Return information

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | Its id, which `undo` takes to restore every ref at once. |
| `moves` | `array of RefMoveOut` | yes | The moves, in the request's order. |
| `op` | `integer` | yes | The operation that recorded every move: its number in `op_log`. |
| `warnings` | `array of string` | no | Problems found after the moves became durable, such as failed housekeeping; the moves themselves succeeded. Omitted when empty. |

Envelope `op`: `ref_txn`.

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 ref list`](ref-list.md)
- [`swarmops ref set`](ref-set.md)
- [`swarmops ref delete`](ref-delete.md)
- [`swarmops ref log`](ref-log.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)