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

Print the JSON Schema of every request and response type, or of TYPE's.

```yaml
title: "swarmops schema"
description: "Print the JSON Schema of every request and response type, or of TYPE's."
group: "store"
since: "0.1.0"
mutates: false
identity_required: false
mcp_tool: ""
envelope_op: "schema"
exit_codes: [0, 2]
errors: [E_INVALID_ARG]
syntax: "swarmops schema [OPTIONS] [TYPE]"
```

## Syntax

```text
swarmops schema [OPTIONS] [TYPE]
```

## Required arguments

None.

## Optional arguments

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

### `TYPE`

Syntax: `<TYPE>`.

One type's name, such as CommitReq.

## Examples

### CLI

```sh
swarmops schema NoSuchType
```

```json
{
  "ok": false,
  "op": "schema",
  "api": 1,
  "error": {
    "code": "E_INVALID_ARG",
    "message": "the schema has no type \"NoSuchType\"",
    "retryable": false,
    "exit": 2,
    "details": {
      "name": "NoSuchType",
      "types": [
        "Advanced",
        "Attribution",
        "BlobHasReq",
        "BlobHasResp",
        "BlobPutReq",
        "BlobPutResp",
        "ChangeInput",
        "ChangeOp",
        "ChangeOut",
        "ChangesetDetail",
        "ChangesetSummary",
        "CommitReq",
        "CommitResp",
        "ConflictKindOut",
        "ConflictReport",
        "ContentEncoding",
        "ContentInput",
        "DeriveReq",
        "DeriveResp",
        "Diff",
        "DiffFormat",
        "DiffHunk",
        "DiffLineOut",
        "DiffReq",
        "DiffStatus",
        "EntryKindOut",
        "Envelope",
        "ErrorCode",
        "FileConflictOut",
        "FileContent",
        "FileDiff",
        "FileKind",
        "GitExportReq",
        "GitExportResp",
        "GitImportReq",
        "GitImportResp",
        "HunkOut",
        "Identity",
        "IdentityInfo",
        "InfoReq",
        "InitReq",
        "LandReq",
        "LandResp",
        "LandStatus",
        "LineOp",
        "LineRange",
        "LinesOut",
        "LogCutOut",
        "LogPage",
        "LogReq",
        "LossyClass",
        "LossyCommitOut",
        "Meta",
        "ModeInput",
        "OpChangesetOut",
        "OpError",
        "OpLogPage",
        "OpLogReq",
        "OperationKind",
        "OperationOut",
        "PathHistoryEntry",
        "PathHistoryPage",
        "PathHistoryReq",
        "ReadFileReq",
        "ReadTreeReq",
        "RecoveredOut",
        "RefDeleteReq",
        "RefListReq",
        "RefListResp",
        "RefMoveOut",
        "RefOut",
        "RefSetReq",
        "RefSetResp",
        "RepoInfo",
        "ResolutionInput",
        "ResolutionsInput",
        "ResolveRevReq",
        "ResolvedRev",
        "Rev",
        "RevKind",
        "ShowReq",
        "Side",
        "SignatureOut",
        "Signatures",
        "TreeEntryOut",
        "TreeListing",
        "UndoReq",
        "UndoResp",
        "VerifyFinding",
        "VerifyReport",
        "VerifyReq"
      ]
    },
    "hint": "swarmops schema"
  },
  "meta": {
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {},
    "auth": "trust"
  }
}
```

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

`schema` prints the JSON Schema of the API's types: every request and response of every
operation, and the types they share, such as `Envelope`, `OpError`, `ChangeInput` and
`ErrorCode`. It is the machine-readable contract behind the JSON the other commands print and
the MCP tools take. It opens no store (`--repo` and `SWARMOPS_REPO` are not read, and the
envelope has no `meta.repo`), needs no identity, and has no MCP tool: an MCP client gets each
tool's input schema from `tools/list` instead.

### What it prints

- Without TYPE, `result` is an object with one entry per type, keyed by the type's name: 91 of
  them in this release.
- With TYPE, `result` is the same object with that one entry, so a script reads
  `result.<TYPE>` either way.

Each entry is a JSON Schema of draft 2020-12 (its `$schema` says so), with the types it uses
under `$defs`, so one entry stands alone. Descriptions are the API's own documentation, the
same text the Return information tables on these pages show.

### Which type to ask for

- A commit's change list: `ChangeInput` (one change), `ContentInput` (its content) and
  `ModeInput`; `CommitReq` is the whole request, as the MCP tool `commit` takes it.
- A land's resolutions file: `ResolutionsInput`, `ResolutionInput` and `Side`.
- A command's result: the type each page's Return information names, such as `CommitResp` or
  `LandResp`.
- The envelope around every result, and its errors: `Envelope`, `Meta` and `OpError`; the
  error codes: `ErrorCode`.

The CLI's flags map onto the request types' fields: `commit --key` is `CommitReq`'s
`idempotency_key`, and `land --resolve` reads a `ResolutionsInput`.

### Patterns

- Generate client types, or validate requests before sending them, from the full output.
- Check a change list against `ChangeInput` before `commit` runs it, rather than learn of a bad
  field from its `E_INVALID_ARG`.
- Find a type's name: an unknown TYPE fails with the list of every name in
  `details.types`.

### Failures

TYPE is matched exactly, case included: `commitreq` is not `CommitReq`. An unknown name is
`E_INVALID_ARG` (exit 2), with `details.name`, `details.types` and the hint `swarmops schema`.

## Return information

`result` is an object of JSON Schemas by type name: TYPE's alone, or every type's.

Envelope `op`: `schema`.

Exit codes:

- `0`: Success.
- `2`: The request or the command line is malformed.

## Errors

- [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2): A malformed argument or request, including a command-line usage error.

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