<!-- 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 init

Create a store in DIR, and describe it.

```yaml
title: "swarmops init"
description: "Create a store in DIR, and describe it."
group: "store"
since: "0.1.0"
mutates: true
identity_required: false
mcp_tool: ""
envelope_op: "repo_init"
exit_codes: [0, 1]
errors: [E_EXISTS, E_UNSUPPORTED_FS]
syntax: "swarmops init [OPTIONS] <DIR>"
```

## Syntax

```text
swarmops init [OPTIONS] <DIR>
```

## Required arguments

### `DIR`

Syntax: `<DIR>`.

The directory to create the store in.

## Optional arguments

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

### `--name`

Syntax: `--name <NAME>`.

The repository's name, at most 255 bytes (default: the directory's name).

## Examples

### CLI

```sh
swarmops init [tmp]/store
```

```json
{
  "ok": true,
  "op": "repo_init",
  "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.

## Details

`init` is the only command that makes a store. It takes the directory as its argument and no
`--repo`: a `--repo` given beside it, or `SWARMOPS_REPO`, is not read, and `meta.repo` in the
envelope is DIR as you wrote it. It needs no identity, and it has no MCP tool: an MCP server
serves a store that exists already.

### What it creates

DIR is created if it is missing, with any missing parent directory. A directory that exists may
hold other files: `init` adds its own beside them. The store is these four entries:

| Entry | What it holds |
| --- | --- |
| `FORMAT` | The layout's version, `swarmops-store 1`. |
| `REPO` | The repository's id, 32 hex digits chosen at random, then its name. |
| `objects/` | The 256 fan-out directories of the loose objects, and `tmp/`. |
| `meta/` | The metadata store: the journal, the index and the refs. |

`FORMAT` is written last. A store is whole once `FORMAT` exists, and a crash or a failed sync
before that leaves no `FORMAT`: other commands refuse the directory, and `init` run again on it
completes the store, with a new repository id. Two `init`s of one directory at once are not
supported.

The new store holds no changeset and no ref, so `main` does not exist yet. The first commit
creates it with `--advance main`; [Start a store's
history](../../guides/commit-and-land.md#start-a-stores-history) shows how.

### The name

`--name` is kept verbatim: any UTF-8 of at most 255 bytes, the empty string included. Without
it, the name is DIR's last component; for `.` or `..`, which have none in the path, it is the
name of the directory they lead to. The name is a label: `info` prints it, and no command looks a
store up by it.

### Patterns

- One store per repository, at a path every agent and script is given, through `--repo` or
  `SWARMOPS_REPO`. There is no default location: [Create a
  store](../../operate/stores.md#create-a-store) uses `~/.local/state/swarmops/repos/<name>`
  as a convention only.
- Set the directory's permissions before agents use it: [Set the
  permissions](../../operate/stores.md#set-the-permissions).
- To start from a git history instead of an empty store, run `init`, then
  [`git import`](../commands/git-import.md).
- Check a new store with [`info`](../commands/info.md) or
  [`verify`](../commands/verify.md).

### Failures

- A directory that holds a store already (a `FORMAT` file) is `E_EXISTS` (exit 1), and nothing
  is written; the hint is `swarmops --repo <dir> info`.
- A name of more than 255 bytes is `E_INVALID_ARG` (exit 2) with `details.store_limit`
  `repo_name_bytes`, `max` and `got`, refused before anything is created.
- A path that leads under `/mnt/`, where WSL mounts Windows drives, is `E_UNSUPPORTED_FS`,
  refused before anything is created. [Where a store may
  live](../../operate/stores.md#where-a-store-may-live) lists the filesystems a store is
  tested on.
- `.` or `..` whose directory has no name gives `E_INVALID_ARG`, with the hint to pass
  `--name`.
- A filesystem that refuses a write is `E_IO`, with the failing `fs_op` in `details`.

## 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_init`.

Exit codes:

- `0`: Success.
- `1`: The operation failed.

## Errors

- [`E_EXISTS`](../errors.md#e_exists) (exit 1): `init` found a store at the target path already.
- [`E_UNSUPPORTED_FS`](../errors.md#e_unsupported_fs) (exit 1): The store path is not on a native Linux filesystem (for example WSL's `/mnt/*`).

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

- [Operating SwarmOps: Create a store](../../operations.md#create-a-store)
- [`swarmops info`](info.md)
- [`swarmops whoami`](whoami.md)
- [`swarmops schema`](schema.md)
- [`swarmops derive`](derive.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)