# swarmops ref log

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

List ref NAME's moves, newest first: the op log filtered to the ref.

A deleted ref lists its moves, the newest with no new value. A name the journal records no move of is E\_REF\_NOT\_FOUND; finding that reads the whole journal.

```yaml
title: "swarmops ref log"
description: "List ref NAME's moves, newest first: the op log filtered to the ref."
group: "refs"
since: "0.11.0"
mutates: false
identity_required: false
mcp_tool: "ref_log"
envelope_op: "ref_log"
exit_codes: [0, 6]
errors: [E_REF_NOT_FOUND]
syntax: "swarmops ref log [OPTIONS] <NAME>"
```

## Syntax

```text
swarmops ref log [OPTIONS] <NAME>
```

## Required arguments

### `NAME`

Syntax: `<NAME>`.

The ref.

## Optional arguments

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

### `--before`

Syntax: `--before <OP>`.

List the moves of operations numbered below OP: the last op of a page reads on from there.

### `--limit`

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

The most moves to list.

## Examples

### CLI

```sh
swarmops --repo [tmp]/store --as agent/worker-17 ref log release/never
```

```json
{
  "ok": false,
  "op": "ref_log",
  "api": 1,
  "error": {
    "code": "E_REF_NOT_FOUND",
    "message": "ref \"release/never\" never existed: the journal records no move of it",
    "retryable": false,
    "exit": 6,
    "details": {
      "name": "release/never"
    },
    "hint": "swarmops ref list names the refs"
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {},
    "auth": "trust"
  }
}
```

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `moves` | `array of RefLogEntryOut` | yes | Its moves. |
| `name` | `string` | yes | The ref. |
| `truncated` | `boolean` | yes | Whether older moves follow this page: give the last one's `op` as `before` to read them. |

Envelope `op`: `ref_log`.

Exit codes:

- `0`: Success.
- `6`: Something the request names does not exist.

## Errors

- [`E_REF_NOT_FOUND`](../errors.md#e_ref_not_found) (exit 6): No ref by that name.

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 txn`](ref-txn.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)