swarmops init#

Create a store in DIR, and describe it.

Metadata

Group: store
Since: 0.1.0
Mutates: yes
Identity required: no
MCP tool: none
Envelope op: repo_init
Exit codes: 01
Errors: E_EXISTS E_UNSUPPORTED_FS

Syntax#

swarmops init [OPTIONS] <DIR>

Required arguments#

Syntax: <DIR>.

The directory to create the store in.

Optional arguments#

The command also takes the global options.

Syntax: --name <NAME>.

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

Examples#

swarmops init [tmp]/store

{
  "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 inits 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 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 uses ~/.local/state/swarmops/repos/<name> as a convention only.
Set the directory's permissions before agents use it: Set the permissions.
To start from a git history instead of an empty store, run init, then git import.
Check a new store with info or verify.

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 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 (exit 1): init found a store at the target path already.
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, E_IO or E_STORE_CORRUPT; a command line the grammar refuses is E_INVALID_ARG (exit 2).