<!-- Generated by crates/swarmops-cli/src/reference.rs from the code: do not edit. Change the code, then run SWARMOPS_REGEN_REFERENCE=1 with the regen_reference test. -->

# swarmops info

Describe the store.

```yaml
title: "swarmops info"
description: "Describe the store."
group: "store"
since: "0.1.0"
mutates: false
identity_required: false
mcp_tool: "repo_info"
envelope_op: "repo_info"
exit_codes: [0, 1, 2, 6]
errors: [E_NOT_A_REPO, E_STORE_CORRUPT, E_INVALID_ARG, E_IO]
syntax: "swarmops info [OPTIONS]"
```

## Syntax

```text
swarmops info [OPTIONS]
```

## Required arguments

None.

## Optional arguments

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

## Examples

### CLI

```sh
swarmops --repo [tmp]/store info
```

```json
{
  "ok": true,
  "op": "repo_info",
  "api": 1,
  "result": {
    "repo_id": "[repo_id]",
    "name": "store",
    "store_version": 1,
    "changesets": 0,
    "refs": 0
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {},
    "auth": "trust"
  }
}
```

Exit code 0. 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.

## Details

`info` opens the store, reads its metadata in one snapshot and prints what the store is and
holds. It reads only: it needs no identity, takes no lock and writes nothing. Its MCP tool is
`repo_info`, which takes no arguments.

### What it reports

- `repo_id` and `name` come from the store's `REPO` file, fixed at [`init`](../commands/init.md).
- `store_version` is the layout version the store's `FORMAT` file names, 1 for every store this
  release makes.
- `changesets` counts every changeset the store holds, those no ref reaches included: a commit
  that was never landed counts.
- `refs` counts the refs, `main` and every `release/<name>`.
- `main` is the full id of the changeset `main` names. The field is left out until `main`
  exists, so a script tells an empty store by its absence.

All five come from the same snapshot, so they agree with each other at one moment. Another
writer may move `main` right after: to build on `main`, read it once and pass that id as
`commit --parent`, as [Publish a change](../../guides/commit-and-land.md#publish-a-change)
does with `resolve main`.

### Patterns

- A health check: `info` exits 0 exactly when the store opens and its metadata reads. Run it
  before handing a store to agents, or from a monitoring job.
- Find the store a script will use: `meta.repo` says which store the command opened, as you
  named it in `--repo` or `SWARMOPS_REPO`.
- Count growth: `changesets` rises with every commit and every land, and never falls, since the
  store removes nothing yet ([Monitoring](../../operate/monitoring.md) lists what else to
  watch).

### Failures

- No store named, neither `--repo` nor `SWARMOPS_REPO`, or an empty `--repo`, is
  `E_NOT_A_REPO` (exit 6). An empty `--repo` does not fall back to `SWARMOPS_REPO`.
- A directory without a `FORMAT` file is `E_NOT_A_REPO`, with the hint `swarmops init <dir>`; a
  `FORMAT` that names another layout version is `E_NOT_A_REPO` too, the store being of a layout
  this build does not read ([Upgrade](../../operate/install-and-upgrade.md#upgrade)).
- A `SWARMOPS_REPO` that is not UTF-8 is `E_INVALID_ARG` (exit 2), with `details.source` naming
  the variable.
- A damaged metadata file is `E_STORE_CORRUPT`, with the hint `swarmops verify`; a store under
  `/mnt/` is `E_UNSUPPORTED_FS`.

## Return information

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `changesets` | `integer` | yes | How many changesets the store holds. |
| `main` | `string or null` | no | The changeset `main` points at; omitted until `main` exists. |
| `name` | `string` | yes | The name given at `init`. |
| `refs` | `integer` | yes | How many refs the store holds. |
| `repo_id` | `string` | yes | The store's id, fixed at `init`. |
| `store_version` | `integer` | yes | The store format version. |

Envelope `op`: `repo_info`.

Exit codes:

- `0`: Success.
- `1`: The operation failed.
- `2`: The request or the command line is malformed.
- `6`: Something the request names does not exist.

## Errors

- [`E_NOT_A_REPO`](../errors.md#e_not_a_repo) (exit 6): No store at the given path, or no store was named.
- [`E_STORE_CORRUPT`](../errors.md#e_store_corrupt) (exit 1): Stored data failed verification.
- [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2): A malformed argument or request, including a command-line usage error.
- [`E_IO`](../errors.md#e_io) (exit 1): The filesystem refused an operation: `details.fs_op` names it, and `details.store_file` the file of the store it was on, relative to the store's root.

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 init`](init.md)
- [`swarmops whoami`](whoami.md)
- [`swarmops schema`](schema.md)
- [`swarmops derive`](derive.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)