> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xdrcheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line reference

> Every command of the kit's tools on one page: the conventions they share, what each command does and its full --help.

For SDK maintainers and indexer operators who run the kit by hand or from CI. It lists every tool and command,
the conventions they share, and each command's own `--help`, so you can find the flag you need and tell from an
exit code whether your reader or the kit failed.

The kit has three main command-line tools, two helper tools (the judge, which the target form of `xdrcheck replay`
calls, and the value tagger), and a `Makefile` that runs them:

| Tool | Language | Built to (linked into `bin/` by `make build`) | What it does |
| - | - | - | - |
| `xdrcheck-corpus` | Rust | `target/release/xdrcheck-corpus` | The corpus toolchain: the oracle (`verify`), the generator (`gen`), intake from the public lake, stellar-core goldens and recipes, decoded sidecars, the reference extractor, the coverage report and the guide's generated table |
| `xdrlint` | Go | `lint/bin/xdrlint` | The linter for Go indexer source |
| `xdrcheck-judge` | Rust | `target/release/xdrcheck-judge` (not linked into `bin/`) | The judge of pipeline replays: facts computed from a ledger's own entry changes (`facts`) and verdicts on a pipeline's exported rows (`verdict`); `xdrcheck replay --target` finds it through `$XDRCHECK_JUDGE` or `PATH` ([replay.md](https://docs.xdrcheck.dev/reference/replay-target.md), `crates/xdrcheck-judge/README.md`) |
| `xdrcheck-tagger` | Rust | `target/release/xdrcheck-tagger` (not linked into `bin/`) | The value tagger: one streaming pass over a lake-layout directory that tags values the shape grammar does not record (wide integers, bytes in text fields, map key order and similar), per partition (`run`), then joined (`merge`) |

`make build` builds all five, the replay adapters (`baseline`, `wallet-backend-adapter`, `stellaretl`) and
`xdrcheck-mutate`, and links each into `./bin` (Rust binaries always go to `./target`, whatever `CARGO_TARGET_DIR` the
shell exports). It ends by printing the line that puts them on your `PATH`:

```sh theme={null}
export PATH="$PWD/bin:$PATH"
```

The examples on this page write bare `xdrcheck`, `xdrcheck-corpus` and `xdrlint` for those binaries. Each section
below has a short summary written by hand and then the tool's own `--help` output, copied verbatim. The help blocks are generated: `scripts/py/check_cli_reference.py` compares them
with the built binaries and fails when they drift (`--write` regenerates them), and it also checks that the table
of `make` targets at the end lists exactly what `make help` prints.

## Conventions shared by every tool

* **Exit codes.** `0`: the command did what it was asked and every check passed. `1`: a check failed (an
  unexpected result, a mismatch, a missing finding). `2`: the tool itself could not run (bad arguments, missing
  input, an integrity mismatch, an adapter or driver that broke its protocol). So `1` means the reader under test failed and `2`
  means the kit did.
* **Network.** Only these commands use the network, and only to fetch pinned, hash-checked inputs:
  `xdrcheck-corpus capture`, `xdrcheck-corpus refetch`, `xdrcheck-corpus fetch-goldens` and `xdrcheck conform fetch` (all reached
  through `make fetch` or run by hand when adding entries). Everything else runs offline; `make &lt;target>
  OFFLINE=1` runs it inside a network namespace with loopback only ([ci-isolation.md](https://docs.xdrcheck.dev/guides/ci.md#offline-and-memory)).
* **Nothing is filed upstream.** No command files, comments on or reports anything to another project.
  `xdrcheck findings issue` writes a draft and prints the command a person would run.
* **Pins.** `--pins FILE` (default `pins.toml`) is the single file of external versions. No tool reads a version
  from anywhere else, and `xdrcheck pins check` fails on any version named elsewhere.
* **Reports.** `--report` writes results in the shared format `xcc.report/v1`
  (`corpus/schema/report.schema.json`), the only format `xdrcheck findings check` and `xdrcheck report` read.
* Public CI never uses it. See `SECURITY.md` and `findings/README.md`.

## Cookbook: replay anything against anything

Each line below was run from the repository root after `make fetch && make build`, with `export PATH="$PWD/bin:$PATH"`
(the `--set public` line as `make verify-conformance-public`, the run `evidence/results/` is made from). After the
fetch all run offline, except `conform fetch --sdk`, which fetches the checkout's own dependencies. An entry ID glob's `*` crosses `/`; `--entries` works the same in `replay` and
`conform run`. `--caps` is `replay`'s alone: in `conform run`, select a CAP's row with `--entries 'cap-0040/*'`. `--input` defaults to the first input the adapter declares, so it is needed only to pick another one.

| To | Run |
| - | - |
| list the entries of a CAP | `xdrcheck entry --cap 40` |
| list entries by ID | `xdrcheck entry --list 'cap-0067/*'` |
| show one entry: tags, variants, expected values, declared divergences, how common it is on mainnet | `xdrcheck entry cap-0040/signed-payload-signer-added` |
| print one variant decoded (SEP-51 JSON) | `xdrcheck entry --decoded testnet cap-0040/signed-payload-signer-added` |
| replay one entry through the baseline adapter | `xdrcheck replay --adapter bin/baseline --target-version dev --entries cap-0040/signed-payload-signer-added` |
| the same through the mock `getLedgers` endpoint, or an S3 store in the lake layout | add `--input rpc`, or `--input sep54-s3` |
| replay one CAP through your own adapter (the Go template; it reads the Galexie layout, `sep54-dir`) | `xdrcheck replay --adapter bin/minimal --target-version 0.1.0 --caps 40` |
| replay the whole corpus, with a report | `xdrcheck replay --adapter bin/baseline --target-version dev --parallel 4 --report reports/baseline` |
| replay through wallet-backend at its pinned commit (needs Docker) | `xdrcheck replay --adapter bin/wallet-backend-adapter --target-version "$(python3 -c 'import tomllib; print(tomllib.load(open("pins.toml","rb"))["pipelines"]["wallet_backend"]["current"])')" --input rpc --entries cap-0040/signed-payload-signer-added` |
| replay through stellar-etl at its pinned commit, from the cache `make fetch` filled | `xdrcheck replay --adapter "bin/stellaretl --offline" --target-version "$(python3 -c 'import tomllib; print(tomllib.load(open("pins.toml","rb"))["pipelines"]["stellar_etl"]["commit"])')" --network testnet --entries 'cap-0040/*'` |
| serve the corpus to any indexer by hand (one mock `getLedgers` URL per replay unit, printed as JSON lines) | `xdrcheck serve --network testnet --rpc 127.0.0.1:8000` |
| run one entry through one SDK column | `xdrcheck conform run --columns 'js@17.4.0' --entries cap-0038/pool-issuers-order-by-bytes-not-strkey` |
| run one entry through every SDK column of the `pr` set (the default) | `xdrcheck conform run --entries cap-0038/pool-issuers-order-by-bytes-not-strkey` |
| run the whole corpus through the widest public set | `xdrcheck conform run --set public --report reports/conformance-public` |
| run an SDK checkout instead of its release (Go, Rust, Python columns) | `xdrcheck conform fetch --columns 'go@v0.9.0' --sdk ../go-stellar-sdk`, then `build` and `run` with the same flags; add `--expected-failures FILE --require-all-read` to `run` to fail only on a new divergence ([use-in-sdk-ci.md](https://docs.xdrcheck.dev/guides/sdk-ci.md) §8) |
| every SDK defect class against every SDK family | `findings/SIBLINGS.md` (`make results-siblings`) |

The `--sdk` copy of a driver is built outside the repository, where a version manager's per-directory toolchain does
not apply: put the pinned Go first on `PATH` (`export PATH="$(go env GOROOT)/bin:$PATH"`, run in the repository)
when your default `go` is older. `--target-version` names the indexer version in the report and, for the pipeline adapters, selects the commit to
build; the baseline and template adapters run one fixed version and record the name you give.

## Commands

* [`xdrcheck-corpus`](#xdrcheck-corpus): the corpus toolchain, the generator and the scan
* [`xdrcheck replay`](#xdrcheck-replay)
* [`xdrcheck serve`](#xdrcheck-serve)
* [`xdrcheck conform`](#xdrcheck-conform)
* [`xdrcheck xcheck`](#xdrcheck-xcheck)
* [`xdrcheck find`](#xdrcheck-find)
* [`xdrcheck data`](#xdrcheck-data)
* [`xdrcheck repro`](#xdrcheck-repro)
* [`xdrcheck runs`](#xdrcheck-runs)
* [`xdrcheck report`](#xdrcheck-report)
* [`xdrcheck mutate`](#xdrcheck-mutate)
* [`xdrcheck pins`](#xdrcheck-pins)
* [`xdrcheck xdr`](#xdrcheck-xdr)
* [`xdrlint`](#xdrlint): the linter
* [`xdrcheck-judge`](#xdrcheck-judge): facts and verdicts
* [`xdrcheck-tagger`](#xdrcheck-tagger): value tags
* `make` targets: [make targets](https://docs.xdrcheck.dev/reference/make-targets.md)

## xdrcheck-corpus

| Command | Does | Used for |
| - | - | - |
| `gen <scenario>… [--network testnet\|pubnet\|core-test\|both] [--protocol N,…] [--profile P]` | Run scenarios on a local stellar-core (offline, standalone, manual close) and write blobs, manifest variants and chain indexes | Generator |
| `gen --check (<scenario>… \| --list FILE \| --all)` | Regenerate and require equal ledger header hashes, transaction hashes and results, and equal bytes after stellar-core's own golden-comparison normalisation | Reproducible generation on both passphrases |
| `capture <network> <ledger> [--tx HASH] [--entry ID]` | Fetch one object from the public SEP-54 data lake verbatim and record its provenance (network) | History entries |
| `mine --network N --range A..B --want PREDICATES [--first K] [--pick smallest\|first] [--except MINED.json] [--max-bytes N] [--step S] [--lake DIR] [--out DIR]` | Stream public-lake objects (anonymous, read-only; `Retry-After` honoured) or a local store directory, walk each ledger, and keep, per wanted predicate (an arm or optional state, an enum value, a result code, a value class, an `SCVal` depth, `uncovered`, `any`), the K smallest matching objects of the range (`--pick first`: the first K); `--except` drops predicates an earlier run satisfied (mine testnet first, then pubnet with `--except`); kept objects are written verbatim with `mined.json` (header and transaction hashes recomputed) (network) | History entries for coverage gaps |
| `refetch [--network N]` | Re-fetch every history entry's object and compare hashes; testnet objects from a reset epoch are reported, not failed (network) | Provenance |
| `fetch-goldens <tag>` | Fetch stellar-core's golden `LedgerCloseMeta` tree at a tag into the cache and verify it against the bulk-tier hash index (network) | Golden agreement, bulk tier |
| `import-golden <tag> <test name> [--frame N] [--entry ID]` | Import one golden ledger as a `core-golden` variant | Golden agreement |
| `synth <recipe>…` | Build synthetic, `api` or `strkey` entries from recipe files | Synthetic and negative entries |
| `slice <entry> <path> --id ID --type XDR_TYPE` | Cut an `xdr` entry out of a ledger entry | One entry per pattern |
| `render [<entry>… \| --all] [--check] [--print ENTRY]` | Write (or check, or print) the SEP-51 decoded sidecars | Expected decoded values |
| `extract <entry>…` | Run the reference extractor: participants, state changes and movements derived from ledger-entry changes and events only | Expected values from an independent source |
| `normalise <file>` | Apply stellar-core's golden-comparison normalisation to a ledger or a record-marked stream | Reproducibility |
| `skeleton <entry> [--scope tx\|ledger]` | Print the structural skeleton (union arms and lengths, leaves masked) and its hash | Golden mirror |
| `chain-index <run dir>` | Write the chain index of a run kept by `gen --keep` | Replay units |
| `coverage [--check]` | Generate `corpus/coverage.json` and `corpus/COVERAGE.md`; with `--check`, fail on drift or on a CAP row with neither an entry nor a stated reason | Per-CAP coverage manifest |
| `index [--check]` | Generate `corpus/index.json`, one row per entry (CAPs, validity, variants, blobs, hashes); with `--check`, fail on drift | Flat corpus index |
| `guide-table [--check]` | Generate the guide's field-by-field table from `corpus/fields.yaml` joined with the manifest; with `--check`, fail on drift | Guide table agrees with the manifest |
| `guide-claims --check` | Check every normative sentence of the guide against its claim record and source | Guide claims match their sources |
| `mainnet fetch [--cache DIR] [--jobs N] [--from DIR]` | Fetch the mainnet tier's public-lake objects (corpus/mainnet (`corpus/mainnet/README.md`)) into `<cache>/mainnet/objects/`: plain HTTPS GETs, each object kept only with the sha256 and size `tier.jsonl` names, one already cached not fetched again (a full cache makes no request); an object the lake now serves with other bytes is kept as `<key>.drift` and fails the run (network) | Mainnet tier |
| `mainnet check [--cache DIR] [--jobs N] [--out TSV]` | The mainnet tier from the cache only: each object's hash, decompression and batch split, each part's bytes and sha256 at its offset, its rs-stellar-xdr round trip, the transaction cut again as `scan cut-slices` cuts it, then the scan's emitter over every ledger: each line's tokens are the transaction's tokens no earlier line holds, and the union is the header's count | Mainnet tier: every transaction-level shape token of the scan, in a real transaction |
| `mainnet coverage [--check]` | Write `evidence/results/mainnet-coverage.json`: of the tier's tokens, how many the tier holds and how many a curated entry's focus transaction holds (walked as `scan entry-tokens` walks it); with `--check`, fail on drift | Coverage statement |
| `mainnet build --cover FILE --token-table FILE [--objects DIR]` | Write `corpus/mainnet/tier.jsonl` and `tier.json` from the scan's rare-first token cover and token table (neither is in the repository) and the lake objects; fails unless every row's new-token count and rarest occurrence are the cover's | How the tier was made |

The global `--corpus DIR` (default `corpus`) selects the corpus root.

### `xdrcheck-corpus --help`

```text theme={null}
Corpus toolchain: oracle, generator, intake, coverage

Usage: xdrcheck-corpus [OPTIONS] <COMMAND>

Commands:
  verify         The oracle gate: schema, ids, hashes, roundtrip, reject, sidecar, pinpoints, ag1, ag3, ag4, extractor
  render         Write SEP-51 decoded sidecars
  extract        Reference extractor: participants, state changes, movements
  normalise      stellar-core golden-comparison normalisation
  skeleton       Structural skeleton and hash
  gen            Run scenarios on a local stellar-core; --check regenerates and compares
  gen-lake       Run exploratory scenarios on a local stellar-core and write the ledgers as a lake
  chain-index    Write a chain index for a kept scenario run
  capture        Fetch one public-lake object verbatim with provenance
  mine           Stream public-lake objects and keep only ledgers with wanted shapes
  refetch        Re-fetch every history entry and compare hashes
  fetch-goldens  Fetch the golden tree at a stellar-core tag
  import-golden  Import one golden ledger as a core-golden variant
  synth          Build synthetic, api or strkey entries from a recipe
  slice          Cut an xdr entry out of a ledger entry
  coverage       Generate coverage.json and COVERAGE.md; --check fails on unexplained gaps
  index          Generate corpus/index.json, one row per entry; --check fails on drift
  guide-table    Generate the guide's field table; --check fails on drift
  guide-claims   Check the guide's claim-to-source map
  mainnet        The mainnet tier: fetch its lake objects, check it, build it from the scan
  scan           Mainnet scan pilot: shape records and the offline tools over them
  help           Print this message or the help of the given subcommand(s)

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
  -h, --help             Print help
  -V, --version          Print version
```

### `xdrcheck-corpus verify --help`

```text theme={null}
The oracle gate: schema, ids, hashes, roundtrip, reject, sidecar, pinpoints, ag1, ag3, ag4, extractor

Usage: xdrcheck-corpus verify [OPTIONS]

Options:
      --corpus <CORPUS>
          Corpus root (directory holding corpus.json, manifest/, blobs/)

          [default: corpus]

      --tier <TIER>
          Tier to verify

          Possible values:
          - curated:   The in-repository corpus (`manifest/`, `blobs/`, `decoded/`)
          - bulk:      The golden set listed in `corpus.json` `tiers.bulk`, read from the golden cache
          - bulk-next: The next-protocol golden set listed in `corpus.json` `tiers.bulk-next`, read from the golden cache under the protocol gate `--max-protocol` lifts it to

          [default: curated]

      --checks <CHECKS>
          Comma-separated checks: schema, hashes, ids, roundtrip, reject, sidecar, pinpoints, ag1, ag3, ag4, extractor, orphans, spec. Default: every check that applies to the tier except ag4

      --entries <ENTRIES>
          Only entries whose ID matches this glob (`*` and `?`); on the bulk tier, golden file paths

      --report <REPORT>
          Write an `xcc.report/v1` report to this file

      --pins <PINS>
          The pins file (only read for the report header)

          [default: pins.toml]

      --goldens <GOLDENS>
          Golden cache root (default `$XDRCHECK_GOLDENS`, else `$HOME/.cache/xdrcheck/goldens`)

      --write-mirrors
          With `ag4` on a whole-corpus run: search the golden set again and rewrite `<corpus>/mirrors.json` (the local-core entries' golden counterparts) before checking


      --max-protocol <N>
          With --tier bulk-next (and only with it, where it is required): the protocol of the next-protocol goldens. The oracle's protocol gate is raised to N for this run only, to see what the pinned definitions fail on; corpus.json can never raise it

  -h, --help
          Print help (see a summary with '-h')
```

### `xdrcheck-corpus render --help`

```text theme={null}
Write SEP-51 decoded sidecars

Usage: xdrcheck-corpus render [OPTIONS] [ENTRIES]...

Arguments:
  [ENTRIES]...  Entry IDs to render

Options:
      --all                Render every manifest entry
      --corpus <CORPUS>    Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --check              Report drift without writing anything
      --print <ENTRY>      Print the decoded JSON of this entry's variant to stdout instead of rendering
      --variant <VARIANT>  With --print: the variant (`network` or `network@protocol`); default: the first
      --pretty             With --print: indent the JSON
  -h, --help               Print help
```

### `xdrcheck-corpus extract --help`

```text theme={null}
Reference extractor: participants, state changes, movements

Usage: xdrcheck-corpus extract [OPTIONS] <ENTRIES>...

Arguments:
  <ENTRIES>...  Entry IDs (`<group>/<slug>`)

Options:
      --corpus <CORPUS>    Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --variant <VARIANT>  Only this variant: `testnet`, `pubnet`, `testnet.p28`, …
  -h, --help               Print help
```

### `xdrcheck-corpus normalise --help`

```text theme={null}
stellar-core golden-comparison normalisation

Usage: xdrcheck-corpus normalise [OPTIONS] <FILE>

Arguments:
  <FILE>  A `LedgerCloseMeta` blob or a record-marked meta stream (golden file, core meta stream)

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --out <OUT>        Write the normalised bytes here instead of stdout
  -h, --help             Print help
```

### `xdrcheck-corpus skeleton --help`

```text theme={null}
Structural skeleton and hash

Usage: xdrcheck-corpus skeleton [OPTIONS] <ENTRY>

Arguments:
  <ENTRY>
          Entry ID (`<group>/<slug>`)

Options:
      --corpus <CORPUS>
          Corpus root (directory holding corpus.json, manifest/, blobs/)

          [default: corpus]

      --variant <VARIANT>
          Only this variant: `testnet`, `pubnet`, `testnet.p28`, …

      --scope <SCOPE>
          Scope of the skeleton

          Possible values:
          - tx:     The variant's focus transaction
          - ledger: The whole ledger

          [default: tx]

  -h, --help
          Print help (see a summary with '-h')
```

### `xdrcheck-corpus gen --help`

```text theme={null}
Run scenarios on a local stellar-core; --check regenerates and compares

Usage: xdrcheck-corpus gen [OPTIONS] [SCENARIOS]...

Arguments:
  [SCENARIOS]...  Scenario files (paths, or relative to the corpus root)

Options:
      --corpus <CORPUS>      Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --network <NETWORK>    testnet, pubnet, core-test, or both (testnet and pubnet) [default: both]
      --protocol <PROTOCOL>  Protocols to run (default: the scenario's)
      --profile <PROFILE>    Meta flag profile (default: the scenario's)
      --check                Regenerate and compare with the committed chains instead of writing
      --list <LIST>          File listing scenario paths, one per line (with --check)
      --all                  Every scenario under <corpus>/scenarios (with --check)
      --runs <RUNS>          Directory for run directories [default: target/xdrcheck-runs]
      --keep                 Keep the run directories
  -h, --help                 Print help
```

### `xdrcheck-corpus gen-lake --help`

```text theme={null}
Run exploratory scenarios on a local stellar-core and write the ledgers as a lake

Usage: xdrcheck-corpus gen-lake [OPTIONS] --out <OUT> [SCENARIOS]...

Arguments:
  [SCENARIOS]...  Scenario files (paths, or relative to the corpus root)

Options:
      --corpus <CORPUS>            Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --out <OUT>                  Output directory; each scenario writes `<out>/<scenario>/`
      --network <NETWORK>          testnet, pubnet or core-test [default: testnet]
      --protocol <PROTOCOL>        Protocol to run (default: the scenario's first)
      --annotations <ANNOTATIONS>  Directory of `<scenario>.json` objects copied into `scenario.json` as `annotations`
      --stream <STREAM>            Export this meta stream instead of running scenarios (needs --name and --passphrase)
      --name <NAME>                Scenario name for --stream
      --passphrase <PASSPHRASE>    Network passphrase of the node that wrote --stream
      --steps <STEPS>              With --stream: a JSON array of the driver's steps (`id`, `property`, `tx_hash`, `submit`: core's answer to the submission); each is placed by its hash
  -h, --help                       Print help
```

### `xdrcheck-corpus chain-index --help`

```text theme={null}
Write a chain index for a kept scenario run

Usage: xdrcheck-corpus chain-index [OPTIONS] <RUN_DIR>

Arguments:
  <RUN_DIR>  A run directory kept by `gen --keep` (holds run.json and meta.xdr)

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --out <OUT>        Write here instead of the corpus's chains/ directory
  -h, --help             Print help
```

### `xdrcheck-corpus capture --help`

```text theme={null}
Fetch one public-lake object verbatim with provenance

Usage: xdrcheck-corpus capture [OPTIONS] <NETWORK> <LEDGER>

Arguments:
  <NETWORK>  `pubnet` or `testnet` (the current testnet epoch pinned in pins.toml)
  <LEDGER>   Ledger sequence

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --tx <TX>          Focus transaction (hash, hex); must be in the ledger
      --entry <ENTRY>    Manifest entry ID whose history variant to add or update
  -h, --help             Print help
```

### `xdrcheck-corpus mine --help`

```text theme={null}
Stream public-lake objects and keep only ledgers with wanted shapes

Usage: xdrcheck-corpus mine [OPTIONS] --network <NETWORK> --range <RANGE> --want <WANT>

Options:
      --corpus <CORPUS>        Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --network <NETWORK>      `pubnet` or `testnet` (the current testnet epoch pinned in pins.toml)
      --range <RANGE>          Inclusive ledger range `A..B`
      --want <WANT>            Wanted predicates, comma-separated (see the module documentation)
      --first <FIRST>          Ledgers kept per predicate [default: 1]
      --pick <PICK>            `smallest`: keep the K smallest matching objects per predicate over the whole range; `first`: keep the first K matching ledgers and stop once every predicate has them [default: smallest]
      --except <EXCEPT>        `mined.json` of an earlier run: drop the predicates it already satisfied (repeatable)
      --max-bytes <MAX_BYTES>  Stop keeping once this many object bytes are kept [default: 67108864]
      --step <STEP>            Look at every STEP-th ledger of the range only [default: 1]
      --jobs <JOBS>            Objects fetched at once [default: 8]
      --lake <LAKE>            Read objects from a local directory laid out like a store instead of the lake
      --out <OUT>              Output directory (default `<cache>/mined`)
  -h, --help                   Print help
```

### `xdrcheck-corpus refetch --help`

```text theme={null}
Re-fetch every history entry and compare hashes

Usage: xdrcheck-corpus refetch [OPTIONS]

Options:
      --corpus <CORPUS>    Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --network <NETWORK>  Only this network (`testnet` or `pubnet`)
  -h, --help               Print help
```

### `xdrcheck-corpus fetch-goldens --help`

```text theme={null}
Fetch the golden tree at a stellar-core tag

Usage: xdrcheck-corpus fetch-goldens [OPTIONS] <TAG>

Arguments:
  <TAG>  stellar-core tag, e.g. v30.0.0

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
  -h, --help             Print help
```

### `xdrcheck-corpus import-golden --help`

```text theme={null}
Import one golden ledger as a core-golden variant

Usage: xdrcheck-corpus import-golden [OPTIONS] <TAG> <TEST_NAME>

Arguments:
  <TAG>        stellar-core tag of the fetched tree, e.g. v30.0.0
  <TEST_NAME>  Human test name from index.json, e.g. "Trustline stellar asset contract|protocol version 30"

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --frame <FRAME>    Ledger of the test to import (0-based record index in the golden file)
      --entry <ENTRY>    Manifest entry ID whose core-golden variant to add or update
  -h, --help             Print help
```

### `xdrcheck-corpus synth --help`

```text theme={null}
Build synthetic, api or strkey entries from a recipe

Usage: xdrcheck-corpus synth [OPTIONS] <RECIPES>...

Arguments:
  <RECIPES>...  Recipe files (JSON, `recipe.schema.json`)

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
  -h, --help             Print help
```

### `xdrcheck-corpus slice --help`

```text theme={null}
Cut an xdr entry out of a ledger entry

Usage: xdrcheck-corpus slice [OPTIONS] --id <ID> --type <XDR_TYPE> <ENTRY> <PATH>

Arguments:
  <ENTRY>  Parent entry ID (a `ledger` or `xdr` entry)
  <PATH>   JSON Pointer into the parent's decoded form

Options:
      --corpus <CORPUS>    Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --id <ID>            ID of the new `xdr` entry (must exist in `plan.json`)
      --type <XDR_TYPE>    XDR type of the value at the pointer, e.g. `TransactionEnvelope`
      --variant <VARIANT>  Parent variant (`network` or `network@protocol`); default: the first
      --offset <OFFSET>    Byte offset of the slice in the parent blob, when the bytes occur more than once
  -h, --help               Print help
```

### `xdrcheck-corpus coverage --help`

```text theme={null}
Generate coverage.json and COVERAGE.md; --check fails on unexplained gaps

Usage: xdrcheck-corpus coverage [OPTIONS]

Options:
      --check                Compare with the committed files and check every row instead of writing
      --corpus <CORPUS>      Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --arms                 Per-arm and per-optional-state coverage instead of the per-CAP table
      --fail-on-regression   With --arms: fail when an arm or state of the baseline is no longer covered
      --write-baseline       With --arms: rewrite the baseline from the current corpus
      --baseline <BASELINE>  With --arms: the baseline file
      --bulk                 With --arms: also walk the cached golden tree (bulk tier)
      --mined <MINED>        With --arms: also walk ledgers kept by `xdrcheck-corpus mine` under this directory
      --report <REPORT>      With --arms: write the full table as JSON
      --universe <UNIVERSE>  With --arms: the root type whose arms are counted: LedgerCloseMetaBatch (ledger data), or SCSpecEntry (the entries of every `spec` entry's contract interface) [default: LedgerCloseMetaBatch]
  -h, --help                 Print help
```

### `xdrcheck-corpus index --help`

```text theme={null}
Generate corpus/index.json, one row per entry; --check fails on drift

Usage: xdrcheck-corpus index [OPTIONS]

Options:
      --check            Compare with the committed corpus/index.json instead of writing it
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --plan             Merge the plan fragments corpus/plan.d/*.json into corpus/plan.json instead (with --check: fail when a fragment row is not in plan.json yet)
  -h, --help             Print help
```

### `xdrcheck-corpus guide-table --help`

```text theme={null}
Generate the guide's field table; --check fails on drift

Usage: xdrcheck-corpus guide-table [OPTIONS]

Options:
      --check            Compare the committed blocks with the generated ones instead of rewriting them
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
      --report <FILE>    Also write the result as an xcc.report/v1 file (one row per citing entry)
  -h, --help             Print help
```

### `xdrcheck-corpus guide-claims --help`

```text theme={null}
Check the guide's claim-to-source map

Usage: xdrcheck-corpus guide-claims [OPTIONS]

Options:
      --check            Check the page against the claim map (the command only checks; the flag is accepted for the documented spelling `guide-claims --check`)
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
  -h, --help             Print help
```

### `xdrcheck-corpus mainnet --help`

```text theme={null}
The mainnet tier: fetch its lake objects, check it, build it from the scan

Usage: xdrcheck-corpus mainnet [OPTIONS] <COMMAND>

Commands:
  fetch     Fill the cache with the tier's lake objects (network step; offline when the cache is full)
  check     Check the tier from the cache: hash chain, cut, round trip, tokens
  build     Write tier.jsonl and tier.json from the scan's token cover and token table
  coverage  Write the token coverage statement (evidence/results/mainnet-coverage.json); --check compares
  help      Print this message or the help of the given subcommand(s)

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
  -h, --help             Print help
```

### `xdrcheck-corpus scan --help`

```text theme={null}
Mainnet scan pilot: shape records and the offline tools over them

Usage: xdrcheck-corpus scan [OPTIONS] <COMMAND>

Commands:
  run             Scan ledgers into shape records
  ablate          Distinct components and transaction shapes at G0–G3, and the ablation table
  cover           Kept-example cover at each level (components and whole transactions)
  saturation      Saturation curves per era on the held-out set
  vocab           Most common event symbols and data-map keys outside the closed vocabularies
  size            Record and dictionary bytes per ledger and per transaction, per era
  format          Per writer era: what the lake serves
  ledgers         Ledgers holding a component (via the transaction shapes that contain it)
  refusals        Refusals of a run: stage, class, error, classification notes
  grep            Components whose tokens contain a text (id, kind, op type, matching tokens)
  ledger-sep      Ledger components: for each ledger, how many run ledgers within a window share its `L` id
  slice-cover     Transaction-slice cover: one transaction per not yet covered component (ledgers ascending), as `seq<TAB>tx_index`
  fetch-bench     Reader throughput: GET every listed ledger from the lake with N parallel requests, keep nothing
  plan-ranges     Cut [first, tip] into a range plan balanced by bytes plus a fixed per-ledger cost
  verify          Prove that run directories hold every ledger of a range plan exactly once
  merge           Merge workers' run directories into one
  supervise       Run N scan workers of a range plan: restart on throttle or crash, heartbeat, watchdog
  list-lake       List lake partitions (anonymous ListObjectsV2) into per-partition size files
  diff            Compare two runs file by file
  recall          Known-trigger recall with independent predicates
  heldout         Held-out recall: pinpointed transactions of corpus entries
  census-extract  Census phase 1: one sorted run file per unit (ids at G0–G3 with counts), unit by unit
  census-merge    Census phase 2: bounded k-way merge of the run files into per-level shape lists and a summary
  cover-stream    Greedy example covers (transactions, whole ledgers; ascending and rarest-first) per level, streaming unit by unit
  token-census    Per token and per token class: carrying components, occurrences, ledger range; projection-step attribution of the O components
  chain-check     Header-hash chain, sequence gaps and invariant bits over every ledger, in ledger order
  locate-build    Build the locate index: token, G3 component and G3 tx shape -> (ledger, transaction) postings
  locate          Where a token, token class, G3 component or G3 tx shape occurs (TSV)
  locate-check    Check the locate index against the token census and the pilot index
  entry-tokens    The shape tokens of every corpus entry's focus transaction (or ledger), walked as `scan run` walks a mainnet ledger
  help            Print this message or the help of the given subcommand(s)

Options:
      --corpus <CORPUS>  Corpus root (directory holding corpus.json, manifest/, blobs/) [default: corpus]
  -h, --help             Print help
```

## xdrcheck replay

Replay the corpus through an indexer's adapter, or ledgers through a target or a rig.

| Command | Does | Used for |
| - | - | - |
| `replay --adapter "CMD" --target-version V [--assert-known] [--report DIR] …` | Replay corpus entries through an adapter and classify each one `pass`, `mishandled` or `dropped` (see [replay-harness.md](https://docs.xdrcheck.dev/reference/replay-harness.md)) | Replay harness |
| `replay --selftest` | Check an adapter's protocol conformance without scoring its indexer | Adapter interface |

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/replay-target.md).

### `xdrcheck replay --help`

```text theme={null}
usage: xdrcheck replay --adapter "COMMAND" --target-version V [flags]
         replay the corpus through an indexer's adapter (the flags below)
       xdrcheck replay --target T --version V (--ledgers L | --tx T | --set S | --cap N | --issue I | --ledger-file F) [flags]
         run an SDK or pipeline target over ledgers and write a run directory (xdrcheck replay --target T --help)
       xdrcheck replay --rig wallet-backend|stellar-etl|horizon --ledgers L --commit C --lake DIR --out DIR [flags]
         run a service rig directly: raw rig output, not a run directory (xdrcheck replay --rig R --help)

Flags of the corpus form:
  -adapter string
    	the adapter's command line (required)
  -assert-known
    	run only entries with a known divergence for this target; fail on any other result than the declared one
  -caps string
    	comma-separated CAP numbers
  -confirm int
    	re-run a unit with a non-pass result K more times; differing results are flaky
  -corpus string
    	corpus root (default "corpus")
  -deadline duration
    	ingest deadline per unit (default: sized from describe.timing)
  -entries string
    	comma-separated entry ID globs
  -input string
    	sep54-s3, sep54-gcs, sep54-dir or rpc (default: the first the adapter declares)
  -keep-going
    	continue after a harness fault
  -keep-state
    	keep each session's state and directories
  -memory-max value
    	memory cap for the adapter's group, for example 1G
  -network string
    	all, testnet, pubnet or core-test (default "all")
  -out-of-envelope string
    	probe or skip: out-of-envelope entries of an indexer_gate adapter (default "probe")
  -parallel int
    	units run at once, each with its own adapter process (default 1)
  -pids-max int
    	process cap for the adapter's group
  -pins string
    	pins file (default pins.toml beside the corpus)
  -repeat int
    	stream: repeat the pass's ledgers K times (default 1)
  -report string
    	write report.json, describe.json, REPORT.md and logs/ here
  -resume
    	skip entries already in the report (not built)
  -selftest
    	check the adapter's protocol conformance without scoring the indexer
  -target-version string
    	version or full commit of the indexer under test (required)
  -unit string
    	auto, single, chain or stream (default "auto")
```

## xdrcheck serve

Serve corpus ledgers as a SEP-54 layout, an object store, or a mock getLedgers.

| Command | Does | Used for |
| - | - | - |
| `serve --network N (--sep54-dir OUT \| --s3 ADDR \| --rpc ADDR)…` | Serve corpus ledgers as a SEP-54 layout on disk, through an S3-compatible store, or as a mock stellar-rpc `getLedgers`, until interrupted; useful for pointing any indexer at the corpus by hand | Ledger delivery |

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/replay-harness.md).

### `xdrcheck serve --help`

```text theme={null}
Usage of xdrcheck serve:
  -chain string
    	serve this chain run as one chain unit
  -corpus string
    	corpus root (default "corpus")
  -delivery-log string
    	append one JSON line per request to this file
  -entries string
    	entry ID glob
  -gcs string
    	GCS endpoint (not built)
  -ledgers string
    	S..E: only ledgers in this range
  -network string
    	pass to serve: testnet, pubnet or core-test (required)
  -pins string
    	pins file (for the object-store image) (default "pins.toml")
  -proxy-to string
    	log and forward to an external emulator (not built)
  -rpc string
    	serve the mock getLedgers here
  -s3 string
    	serve the layouts from an S3 store whose logging proxy listens here
  -sep54-dir string
    	write each unit's SEP-54 layout under this directory
  -stream-base uint
    	first sequence of a stream unit (default 1000)
  -unit string
    	single, chain or stream (default: what each entry needs)
```

## xdrcheck conform

Run the corpus through SDK conformance drivers.

| Command | Does | Used for |
| - | - | - |
| `conform fetch` / `build` | Fill each driver directory's package cache from its lock files (network), then build the drivers offline | Conformance runner |
| `conform run [--set NAME \| --columns GLOB] [--report DIR]` | Run entries through the SDK drivers and write the divergence matrix (`matrix.json`, `matrix.md`, `cross-sdk.md`, `report.json`) | Divergence matrix |
| `conform check <matrix.json>` | Fail on any cell that is undeclared, conforms where a divergence is declared, or diverges differently, and on a required column that judged no cell | Regression test across SDKs |
| `conform diff <a> <b>`, `conform readiness [--protocol N] [--report DIR]` | Cells that changed between two runs; which pinned SDK versions decode each protocol's and CAP's shapes (`full`, `partial n of m`, `refuses new arms`, `not run`), as `readiness.md` and `readiness.json` | Upgrade review |

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/driver-protocol.md#conformance-rules).

### `xdrcheck conform --help`

```text theme={null}
usage: xdrcheck conform fetch|build|run|describe|check|diff|readiness [flags]
```

### `xdrcheck conform fetch --help`

```text theme={null}
Usage of xdrcheck conform fetch:
  -column value
    	one SDK's columns by name, for example soroban-spec (every version and profile of it); repeatable
  -columns string
    	comma-separated column globs, for example 'js@17.*,go@*'
  -pins string
    	pins file (default pins.toml at the repository root)
  -sdk string
    	build and run the selected columns from this SDK checkout instead of their pinned package (one SDK's columns, for example --column go --sdk ../go-stellar-sdk); fetch, build and run all need it
  -set string
    	named column set from drivers/sets.toml (default pr)
```

### `xdrcheck conform build --help`

```text theme={null}
Usage of xdrcheck conform build:
  -column value
    	one SDK's columns by name, for example soroban-spec (every version and profile of it); repeatable
  -columns string
    	comma-separated column globs, for example 'js@17.*,go@*'
  -pins string
    	pins file (default pins.toml at the repository root)
  -sdk string
    	build and run the selected columns from this SDK checkout instead of their pinned package (one SDK's columns, for example --column go --sdk ../go-stellar-sdk); fetch, build and run all need it
  -set string
    	named column set from drivers/sets.toml (default pr)
```

### `xdrcheck conform run --help`

```text theme={null}
Usage of xdrcheck conform run:
  -as-limit value
    	address-space cap (RLIMIT_AS) per driver process (0 = none)
  -column value
    	one SDK's columns by name, for example soroban-spec (every version and profile of it); repeatable
  -columns string
    	comma-separated column globs, for example 'js@17.*,go@*'
  -entries string
    	comma-separated entry ID globs ('*' crosses '/')
  -expected-failures string
    	the column's expected-failure list: the run passes only when its failing cells are exactly the list (a new failure or a listed cell that passes fails it); needs one column
  -goldens string
    	golden cache root for --tier bulk (default $XDRCHECK_GOLDENS, else ~/.cache/xdrcheck/goldens)
  -jobs int
    	columns run in parallel (default the number of CPUs)
  -kind string
    	only entries of this kind (ledger, xdr, api, strkey, spec); --kind spec with neither --set nor --columns selects the spec set
  -level string
    	the same as --levels; --level json with neither --set nor --columns selects the json set
  -levels string
    	comma-separated levels, for example L0,L1 or spec or json (default every applicable level)
  -memory-max value
    	memory cap per driver process, for example 1G or 512M (0 = none) (default 1073741824)
  -pins string
    	pins file (default pins.toml at the repository root)
  -report string
    	directory for matrix.json, matrix.md, cross-sdk.md, report.json, cells.ndjson and describe.json
  -require-all-read
    	fail the run when a column never read a selected entry variant (every level n/a, or no level its driver answers)
  -sdk string
    	build and run the selected columns from this SDK checkout instead of their pinned package (one SDK's columns, for example --column go --sdk ../go-stellar-sdk); fetch, build and run all need it
  -set string
    	named column set from drivers/sets.toml (default pr)
  -tier string
    	corpus tier: curated or bulk (default "curated")
  -timeout duration
    	per-request base timeout; a request gets it once more per MiB of input (default 20s)
  -write-expected-failures string
    	write the column's failing cells to this file as an expected-failure list; needs one column
```

### `xdrcheck conform describe --help`

```text theme={null}
Usage of xdrcheck conform describe:
  -column value
    	one SDK's columns by name, for example soroban-spec (every version and profile of it); repeatable
  -columns string
    	comma-separated column globs, for example 'js@17.*,go@*'
  -pins string
    	pins file (default pins.toml at the repository root)
  -sdk string
    	build and run the selected columns from this SDK checkout instead of their pinned package (one SDK's columns, for example --column go --sdk ../go-stellar-sdk); fetch, build and run all need it
```

### `xdrcheck conform check --help`

```text theme={null}
Usage of xdrcheck conform check:
  -min-judged int
    	judged (not n_a) cells every required column must have (default 1)
  -mode string
    	development (pending cells are reported and pass) or acceptance (they fail) (default "development")
```

### `xdrcheck conform diff --help`

```text theme={null}
usage: xdrcheck conform diff <matrix-a> <matrix-b>
```

### `xdrcheck conform readiness --help`

```text theme={null}
Usage of xdrcheck conform readiness:
  -protocol int
    	only the entries introduced at this protocol (default every protocol)
  -report string
    	the run's report directory: read its matrix.json (unless one is named) and write readiness.md and readiness.json into it
```

## xdrcheck xcheck

The same transactions through two or more targets or versions; diff the fields both compute.

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/driver-protocol.md#xcheck).

### `xdrcheck xcheck --help`

```text theme={null}
Usage of xdrcheck xcheck:
  -corpus string
    	corpus root (for --cap, --issue and corpus ledgers) (default "corpus")
  -dataset string
    	dataset directory (default $XDRCHECK_DATASET, else the per-user data directory)
  -lake string
    	ledger cache in lake layout (default $XDRCHECK_LAKE, else <dataset>/lake)
  -lake-url string
    	lake URL to fetch missing ledgers from (default: the public pubnet lake)
  -ledger-file value
    	a ledger object file; repeatable
  -ledgers string
    	ledgers: comma-separated sequences and ranges a-b, or @FILE
  -max-ledgers int
    	refuse selections larger than this (default 2000)
  -network string
    	pubnet or testnet (default: pubnet, or the network of the issue or corpus entry)
  -offline
    	never use the network: no ledger download, no target fetch
  -out string
    	output directory (default xcheck/<time>)
  -parallel int
    	downloads in flight (at most 256) (default 64)
  -rate float
    	download requests per second, 0 for no cap (default 200)
  -rules
    	print the normalisation rules and exit
  -set string
    	a named set of the dataset
  -target value
    	TARGET@VERSION (go, js, python or rust); give two or more; repeatable
  -tx value
    	a transaction LEDGER:INDEX; repeatable
```

## xdrcheck find

Example transactions for a token, class, value tag, CAP, assumption or operation type.

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/replay-target.md#find).

### `xdrcheck find --help`

```text theme={null}
Usage of xdrcheck find:
  -assumption string
    	a linter assumption key (for example text-to-db:memo); --list-assumptions shows the mapped keys
  -cap int
    	the corpus examples of a CAP, and the dataset's cap-N set
  -class string
    	every token of a class, K|class (for example V|u64band)
  -corpus string
    	corpus root (for --cap) (default "corpus")
  -dataset string
    	dataset directory (default $XDRCHECK_DATASET, else the per-user data directory)
  -format string
    	tsv, json or ledgers (one ledger per line, for --ledgers @FILE) (default "tsv")
  -limit int
    	examples to print (default 20)
  -list-assumptions
    	print the assumption keys find can map to ledgers
  -op string
    	an operation type (for example PATH_PAYMENT_STRICT_SEND)
  -order string
    	first, last, rarest (by census occurrences of the matched token) or random (default "first")
  -seed uint
    	seed of --order random (default 1)
  -set string
    	a named set of the dataset
  -source string
    	auto (locate index, else the kept-ledger index), locate or kept (default "auto")
  -tag string
    	a value tag (for example u64>=2^63); a trailing * matches a prefix
  -token string
    	a token, as its text (K|class|path) or its 32-hex id
  -token-contains string
    	every token whose text contains this string (kept-ledger index only)
```

## xdrcheck data

The dataset: status, named ledger sets, ledger fetch, manifest, top-up plan.

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/replay-target.md#dataset).

### `xdrcheck data --help`

```text theme={null}
usage: xdrcheck data <subcommand> [flags]

subcommands:
  status    the dataset present: version, tip ledger, tables and sets with their files (--verify: sha256)
  sets      the named ledger sets shipped with the dataset
  fetch     download ledgers from the public lake into the local ledger cache (size and MD5 checked)
  manifest  write a dataset manifest for derived data under named roots
  update    print the plan of an append-only top-up from the dataset's tip (does not scan)
  export    copy named sets (and small tables) with a manifest into a portable dataset directory, for CI
```

## xdrcheck repro

Pack a run's result into a self-contained bundle, run a bundle, verify its input.

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/replay-target.md#repro).

### `xdrcheck repro --help`

```text theme={null}
usage: xdrcheck repro pack RUN_DIR --cluster KEY [--tx LEDGER:INDEX] [--out DIR]
       xdrcheck repro run BUNDLE [--version V] [--out DIR]
       xdrcheck repro verify BUNDLE
```

## xdrcheck runs

Validate run directories and compare two runs by cluster.

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/replay-target.md#run-directory).

### `xdrcheck runs --help`

```text theme={null}
usage: xdrcheck runs validate DIR...
       xdrcheck runs compare DIR_A DIR_B
```

## xdrcheck report

Build, redact and diff reports.

| Command | Does | Used for |
| - | - | - |
| `report redact <report>`, `report diff <a> <b>` | A copy of a report with evidence strings removed, safe to share; rows that changed between two reports | Third-party runs; upgrade review |

### `xdrcheck report --help`

```text theme={null}
usage: xdrcheck report acceptance|redact|diff [flags] <args>
```

### `xdrcheck report redact --help`

```text theme={null}
Usage of xdrcheck report redact:
  -out string
    	output file (default standard output)
```

### `xdrcheck report diff --help`

```text theme={null}
Usage of xdrcheck report diff:
```

## xdrcheck mutate

Structure-aware mutants of corpus values through every reader.

The full description is on [its reference page](https://docs.xdrcheck.dev/reference/driver-protocol.md#mutation).

### `xdrcheck mutate --help`

```text theme={null}
usage: xdrcheck mutate run|replay|minimise|promote [flags]
```

### `xdrcheck mutate run --help`

```text theme={null}
Usage of xdrcheck mutate run:
  -adapter-deadline duration
    	ingest deadline per replay unit (default: sized from the adapter's describe)
  -adapter-memory-max value
    	memory cap for an adapter's process group (default 4294967296)
  -adapter-parallel int
    	replay units run at once per adapter (default 4)
  -adapters string
    	replay adapters: all, none, or wallet-backend,stellar-etl,baseline (default "all")
  -all-variants
    	every variant of an entry, not only the first
  -as-limit value
    	address-space cap (RLIMIT_AS) per driver process: SIZE for every column, or GLOB=SIZE,… per column (0 = none)
  -budget int
    	mutants to build (default 2000)
  -classes string
    	mutator classes (default "valid,metamorphic,wire-invalid")
  -columns string
    	conformance columns: all, none, or comma-separated column globs (default "all")
  -entries string
    	source entry ID globs, comma-separated
  -jobs int
    	conformance columns run in parallel (default the number of CPUs)
  -max-bytes int
    	largest corpus value used as a source (default 262144)
  -memory-max value
    	memory cap per driver process (0 = none) (default 1073741824)
  -minimise int
    	candidates minimised at most (each costs a run of its readers per mutation) (default 400)
  -mutate-bin string
    	the xdrcheck-mutate binary (default $XDRCHECK_MUTATE_BIN, else target/release/xdrcheck-mutate)
  -mutators string
    	mutator IDs (default every mutator of the classes)
  -no-cut
    	do not cut envelopes and SCVals out of ledgers as sources
  -no-suppress
    	report signatures that match existing findings too
  -pins string
    	pins file (default pins.toml at the repository root)
  -report string
    	report directory (default <work>/report)
  -seed uint
    	seed (default 1)
  -set string
    	named column set (with --columns other than all or none)
  -stale-hashes
    	leave ledger hashes stale after a valid-preserving mutation
  -timeout duration
    	per-request base timeout of a driver (default 20s)
  -work string
    	work directory for the mutant corpus and the runners' reports (outside the repository)
```

### `xdrcheck mutate replay --help`

```text theme={null}
Usage of xdrcheck mutate replay:
  -adapter-deadline duration
    	ingest deadline per replay unit (default: sized from the adapter's describe)
  -adapter-memory-max value
    	memory cap for an adapter's process group (default 4294967296)
  -adapter-parallel int
    	replay units run at once per adapter (default 4)
  -as-limit value
    	address-space cap (RLIMIT_AS) per driver process: SIZE for every column, or GLOB=SIZE,… per column (0 = none)
  -entry string
    	the mutant's source: an entry ID, or <entry>#<path> for a value cut from a ledger
  -jobs int
    	conformance columns run in parallel (default the number of CPUs)
  -memory-max value
    	memory cap per driver process (0 = none) (default 1073741824)
  -mutate-bin string
    	the xdrcheck-mutate binary (default $XDRCHECK_MUTATE_BIN, else target/release/xdrcheck-mutate)
  -mutation string
    	mutation IDs, comma-separated, in order
  -pins string
    	pins file (default pins.toml at the repository root)
  -print string
    	print only this reader's verdict line
  -readers string
    	readers: column IDs and adapters (name or name@version), 'columns' or 'all' (default "all")
  -seed uint
    	seed (default 1)
  -stale-hashes
    	leave ledger hashes stale after a valid-preserving mutation
  -timeout duration
    	per-request base timeout of a driver (default 20s)
  -variant int
    	the source's variant index
  -work string
    	work directory for the mutant corpus and the runners' reports (outside the repository)
```

### `xdrcheck mutate minimise --help`

```text theme={null}
Usage of xdrcheck mutate minimise:
  -adapter-deadline duration
    	ingest deadline per replay unit (default: sized from the adapter's describe)
  -adapter-memory-max value
    	memory cap for an adapter's process group (default 4294967296)
  -adapter-parallel int
    	replay units run at once per adapter (default 4)
  -as-limit value
    	address-space cap (RLIMIT_AS) per driver process: SIZE for every column, or GLOB=SIZE,… per column (0 = none)
  -entry string
    	the mutant's source: an entry ID, or <entry>#<path> for a value cut from a ledger
  -jobs int
    	conformance columns run in parallel (default the number of CPUs)
  -memory-max value
    	memory cap per driver process (0 = none) (default 1073741824)
  -mutate-bin string
    	the xdrcheck-mutate binary (default $XDRCHECK_MUTATE_BIN, else target/release/xdrcheck-mutate)
  -mutation string
    	mutation IDs, comma-separated, in order
  -pins string
    	pins file (default pins.toml at the repository root)
  -reader string
    	the reader whose verdict is kept
  -readers string
    	readers to judge with (default the reader and the stellar-core column; a split needs the run's columns)
  -seed uint
    	seed (default 1)
  -stale-hashes
    	leave ledger hashes stale after a valid-preserving mutation
  -timeout duration
    	per-request base timeout of a driver (default 20s)
  -variant int
    	the source's variant index
  -work string
    	work directory for the mutant corpus and the runners' reports (outside the repository)
```

### `xdrcheck mutate promote --help`

```text theme={null}
Usage of xdrcheck mutate promote:
  -adapter-deadline duration
    	ingest deadline per replay unit (default: sized from the adapter's describe)
  -adapter-memory-max value
    	memory cap for an adapter's process group (default 4294967296)
  -adapter-parallel int
    	replay units run at once per adapter (default 4)
  -as-limit value
    	address-space cap (RLIMIT_AS) per driver process: SIZE for every column, or GLOB=SIZE,… per column (0 = none)
  -entry string
    	the mutant's source: an entry ID, or <entry>#<path> for a value cut from a ledger
  -id string
    	the new entry's ID
  -into string
    	corpus root to write into
  -jobs int
    	conformance columns run in parallel (default the number of CPUs)
  -memory-max value
    	memory cap per driver process (0 = none) (default 1073741824)
  -mutate-bin string
    	the xdrcheck-mutate binary (default $XDRCHECK_MUTATE_BIN, else target/release/xdrcheck-mutate)
  -mutation string
    	mutation IDs, comma-separated, in order
  -pins string
    	pins file (default pins.toml at the repository root)
  -public
    	allow writing into the repository's corpus (the ID must then be in corpus/plan.json)
  -seed uint
    	seed (default 1)
  -stale-hashes
    	leave ledger hashes stale after a valid-preserving mutation
  -timeout duration
    	per-request base timeout of a driver (default 20s)
  -variant int
    	the source's variant index
  -work string
    	work directory for the mutant corpus and the runners' reports (outside the repository)
```

## xdrcheck pins

Check that every version used matches pins.toml.

| Command | Does | Used for |
| - | - | - |
| `pins check` | Every toolchain file, lock file, image and download agrees with `pins.toml` | Pinned, reproducible builds |
| `pins check --today D`, `pins check --network` | The `pins.toml` `[[schedule]]` events (mainnet votes, testnet resets) read against a date; with `--network`, the Horizon roots of mainnet and testnet and the status page against the pins ([maintenance.md §5.5](https://docs.xdrcheck.dev/guides/maintain-kit.md)) | Dated upgrades and resets do not pass unnoticed |
| `pins latest [--list]` | Each pin with a `# renovate:` annotation against the newest stable upstream release (`--list`: the annotated pins only, offline) | Pin moves ([maintenance.md §5.3](https://docs.xdrcheck.dev/guides/maintain-kit.md)) |

### `xdrcheck pins --help`

```text theme={null}
usage: xdrcheck pins check [--pins FILE] [--today YYYY-MM-DD] [--network]
       xdrcheck pins latest [--pins FILE] [--json FILE] [--list]
```

## xdrcheck xdr

Diff XDR definition sets, watch upstream, generate driver ceilings and candidate rows.

| Command | Does | Used for |
| - | - | - |
| `xdr diff <base> <head>` | Structural diff of two XDR definition sets (a `.x` directory, a definitions JSON, `pinned`, or any stellar-xdr git ref): types, enum members, struct fields, union arms with numeric cases, optionality and size bounds; each change with its `#ifdef` gate, the CAP that gate names, and whether `LedgerCloseMetaBatch` or `TransactionEnvelope` reaches it; JSON and Markdown | Upgrade review |
| `xdr watch --out DIR` | Diff every source of unreleased XDR (main, branches, pull requests, pending CAP documents, standing items) against the pins; `watch-log.jsonl`, a digest per upcoming protocol, per-source diffs | Upgrade watch |
| `xdr candidates <diff.json>…` | Candidate `caps.toml`, `arms.toml` and `plan.json` rows for the new shapes of diffs, each marked for review; `--write` edits the files | Upgrade review |
| `xdr ceilings --check\|--write` | The conformance drivers' sentinel-enum ceilings against the pinned XDR definitions | Driver upkeep |

### `xdrcheck xdr --help`

```text theme={null}
usage: xdrcheck xdr diff|ceilings|candidates|watch [flags]
```

### `xdrcheck xdr diff --help`

```text theme={null}
usage: xdrcheck xdr diff [flags] <base> <head>

base and head: a directory of .x files, a definitions .json(.zst), `pinned`, or a stellar-xdr git ref.
  -base-features string
    	features enabled in the base: none, all, or a comma-separated list (default "none")
  -cap string
    	attribute every change to this CAP (CAP-NNNN), e.g. for a CAP document's own diff
  -exit-code
    	exit 1 when the sets differ
  -format string
    	what to print: md or json (default "md")
  -head-features string
    	features enabled in the head: none, all, or a comma-separated list (default "all")
  -json string
    	also write the JSON report to this file
  -md string
    	also write the Markdown report to this file
  -repo string
    	git repository git refs are read from (default "https://github.com/stellar/stellar-xdr.git")
  -roots string
    	types whose reachability marks a change as reader-visible (default "LedgerCloseMetaBatch,TransactionEnvelope")
```

### `xdrcheck xdr ceilings --help`

```text theme={null}
Usage of xdrcheck xdr ceilings:
  -check
    	fail (exit 1) when a block differs from the definitions; write nothing
  -defs string
    	the definitions: a .x directory, a definitions .json(.zst) or a stellar-xdr git ref (default: the vendored pinned definitions, crates/xdrcheck-corpus/data/xdr-definitions-v30.0.0.json.zst)
  -dir string
    	directory searched for ceiling blocks (default "drivers")
  -label string
    	the definitions' label written on each block's BEGIN line (default: stellar-xdr <pinned tag>)
  -repo string
    	git repository a git ref is read from (default "https://github.com/stellar/stellar-xdr.git")
  -write
    	rewrite every block from the definitions
```

### `xdrcheck xdr candidates --help`

```text theme={null}
usage: xdrcheck xdr candidates [flags] (--from candidates.txt | <diff.json>...)
  -caps-info xdrcheck xdr watch
    	CAP preambles as xdrcheck xdr watch writes them (caps.json)
  -corpus string
    	corpus directory holding caps.toml, arms.toml and plan.json (default "corpus")
  -from string
    	a file listing diff reports, one per line, relative to its own directory (candidates.txt of a watch run)
  -next-protocol int
    	protocol for rows no CAP names (default: pins.toml max_supported + 1)
  -write
    	rewrite the three files in place (default: write nothing, list the rows)
```

### `xdrcheck xdr watch --help`

```text theme={null}
Usage of xdrcheck xdr watch:
  -api string
    	GitHub API base URL (read-only; GH_TOKEN or GITHUB_TOKEN is sent when set) (default "https://api.github.com")
  -github-repo string
    	the same repository as owner/name, for listing open pull requests (default "stellar/stellar-xdr")
  -next-protocol int
    	the next protocol (default: pins.toml max_supported + 1)
  -out string
    	output directory (required)
  -previous string
    	the previous run's watch-log.jsonl, carried over and used to mark what is new
  -protocol-repo string
    	the CAP repository (default "https://github.com/stellar/stellar-protocol.git")
  -repo string
    	the XDR definitions repository (default "https://github.com/stellar/stellar-xdr.git")
  -skip string
    	parts not to run, comma-separated: main, branches, prs, caps
  -standing string
    	stellar-xdr branches always reported, comma-separated (default "lcm_v3")
```

## xdrlint

The rules: [xdrlint rules](https://docs.xdrcheck.dev/reference/lint-rules.md).

`xdrlint` runs the rules over Go packages and prints findings with rule IDs; it exits 1 when an unsuppressed
finding at or above `-fail-on` exists, and 2 (with a warning) when none of the packages it loaded, nor anything
they import, is go-stellar-sdk's `xdr` package, since its rules then have nothing to analyse. The same analyzers
run as a `go vet` tool (`go vet -vettool=$(which xdrlint) ./...`) and inside golangci-lint as a module plugin
(`make lint-plugin`). Each rule has its own page under [`lint/docs/`](https://docs.xdrcheck.dev/reference/lint-rules).

### `xdrlint -h`

```text theme={null}
usage: xdrlint [flags] <packages>
       go vet -vettool=$(which xdrlint) <packages>

flags:
  -config FILE
    	project configuration FILE (default: .xdrlint.yml found from the working directory up to the module root)
  -docs-base BASE
    	where diagnostics link the rule pages: BASE/XDR103.md, or a URL template with {rule} (env XDRLINT_DOCS_BASE) (default "lint/docs")
  -expect FILE
    	compare (rule, file, function, suppressed) of the reports with the expected list in FILE; exit 1 on any difference
  -fail-on string
    	lowest severity that fails the run: error, warning or info (default "error")
  -json
    	print diagnostics as JSON
  -profile NAME
    	shipped profile NAME or profile file PATH
  -report FILE
    	write every diagnostic, suppressed ones included, as xcc.report/v1 to FILE
  -sarif FILE
    	write SARIF 2.1.0 to FILE

shipped profiles: default, fixtures, wallet-backend

rules in this build:
  XDR000 (error) suppression without a reason, naming an unknown rule, or suppressing nothing
  XDR101 (error) address built from a memo
  XDR102 (error) unnormalised address used as an identity key
  XDR103 (error) unvalidated bytes or string into text storage
  XDR105 (warning, opt-in) Must<Arm>() on a multi-arm union without a dominating discriminant check
  XDR201 (warning) recursion over a self-referential xdr type with no depth bound
  XDR202 (warning) iterative walker with an unbounded worklist
  XDR203 (warning) decoded integer used as an allocation size or loop bound
  XDR204 (info, opt-in) persisted serialisation of a recursive value with no length check
  XDR205 (error) decoder with limits disabled
  XDR206 (warning) behaviour at a bound differs from the declared overflow policy
  XDR207 (warning) bound below what stellar-core admits, on a path fed from ledger meta
  XDR301 (error) participants harvested from the authorization tree or invocation arguments
  XDR302 (error) envelope operation fields used as participants without a success gate
  XDR303 (warning) participant builder that never reads meta
  XDR304 (error) token-shaped contract event trusted without checking the emitting contract
  XDR401 (error) one meta version assumed: an arm read without a version check, or a version check that halts on the others
  XDR402 (error) wide integer narrowed without a range check and stored
  XDR403 (warning) error or ok result discarded on a value that is then stored
  XDR404 (error) contract event topics or data trusted by position or kind without a shape or emitter check
  XDR405 (error) rows from diagnostic events without a success gate, or from transaction-level changes in operation scope
  XDR406 (warning, opt-in) closed switch over an xdr enum that writes rows, with no default or a panicking default
```

## xdrcheck-judge

Facts from a ledger's own entry changes, and verdicts on an indexer's rows. What it computes: [Judge](https://docs.xdrcheck.dev/reference/judge.md).

### `xdrcheck-judge --help`

```text theme={null}
Ground truth from LedgerCloseMeta, and verdicts on indexer rows

Usage: xdrcheck-judge <COMMAND>

Commands:
  facts    Compute facts (JSONL) for ledgers; optionally run the conservation self-check
  verdict  Compare an indexer's rows with facts and emit verdicts
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
```

### `xdrcheck-judge facts --help`

```text theme={null}
Compute facts (JSONL) for ledgers; optionally run the conservation self-check

Usage: xdrcheck-judge facts [OPTIONS] [FILES]...

Arguments:
  [FILES]...  Ledger files (zstd LedgerCloseMetaBatch or raw XDR), processed in the order given

Options:
      --root <ROOT>                  A lake-layout directory with `index.tsv` (seq, path, size)
      --list <LIST>                  Ledger sequences to take from --root (first column of each line; `#`/non-numeric skipped)
      --network <NETWORK>            [default: "Public Global Stellar Network ; September 2015"]
      --sac-registry <SAC_REGISTRY>  Extra SAC candidates: one asset string (`native`, `CODE:ISSUER`) per line
  -o, --out <OUT>                    Facts output (`-` = stdout). Omit to write none
      --conserve <CONSERVE>          Write `residuals.jsonl` and `summary.json` of the conservation check here
  -j, --jobs <JOBS>                  [default: 4]
  -h, --help                         Print help
```

### `xdrcheck-judge verdict --help`

```text theme={null}
Compare an indexer's rows with facts and emit verdicts

Usage: xdrcheck-judge verdict [OPTIONS] --facts <FACTS> --rows <ROWS> --out <OUT>

Options:
      --facts <FACTS>                  
      --rows <ROWS>                    
  -o, --out <OUT>                      
      --balance-scope <BALANCE_SCOPE>  `net`: rows carry fees too; `nofee`: rows exclude fee and refund changes [default: net]
      --kinds <KINDS>                  Kinds to compare (default: every kind present in the rows)
      --roles <ROLES>                  Participant roles that count (default: all)
      --scope <SCOPE>                  The target's scope file (TOML): kinds, comparison modes, out-of-scope rules
  -h, --help                           Print help
```

## xdrcheck-tagger

Tag dangerous values in ledger bytes, partition by partition. What it computes: [The mainnet scan](https://docs.xdrcheck.dev/architecture/mainnet-scan.md).

### `xdrcheck-tagger --help`

```text theme={null}
Tag dangerous values in ledger bytes

Usage: xdrcheck-tagger <COMMAND>

Commands:
  run    Tag every ledger of a lake-layout directory, one output set per partition
  merge  Join the partition outputs into the final files
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
```

### `xdrcheck-tagger run --help`

```text theme={null}
Tag every ledger of a lake-layout directory, one output set per partition

Usage: xdrcheck-tagger run [OPTIONS] --root <ROOT> --out <OUT>

Options:
      --root <ROOT>              Lake-layout directory (`<partition>/<object>.xdr.zst`)
      --index <INDEX>            `seq<TAB>path<TAB>size` of the ledgers (default: ROOT/index.tsv)
      --out <OUT>                Output directory
      --jobs <JOBS>              Partitions worked at once [default: 8]
      --range <RANGE>            Only ledgers in a..b (inclusive)
      --row-cap <ROW_CAP>        Rows written per (tag, path) and partition [default: 5000]
      --passphrase <PASSPHRASE>  Network passphrase (SAC ids, transaction hashes) [default: "Public Global Stellar Network ; September 2015"]
      --check-size               Check each object's size against the index
  -h, --help                     Print help
```

### `xdrcheck-tagger merge --help`

```text theme={null}
Join the partition outputs into the final files

Usage: xdrcheck-tagger merge [OPTIONS]

Options:
      --out <OUT>  Output directory of `run` (one or more; partitions are joined in ledger order)
      --to <TO>    Directory for the merged files (default: the first --out)
  -h, --help       Print help
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.