cairn-lang-cli 2026.8.2

Command-line interface for the Cairn language
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# cairn-lang-cli

The `cairn` command-line interface. This is the only Cairn crate that ships an executable; it wires
the [`cairn-lang-core`](../cairn-lang-core/README.md) compiler, the format backends in
[`cairn-lang-formats`](../cairn-lang-formats/README.md), and (when described logically) the redstone synthesizer
in [`cairn-lang-redstone`](../cairn-lang-redstone/README.md) into the subcommands an author actually types.

## Status

Skeleton. The current binary recognizes `--version` / `--help` and prints a stub usage block; every
real subcommand returns a "not implemented yet" error.

## Subcommands (planned)

The CLI surface follows the spec; each subcommand maps onto a chapter so the help text and the
normative document can never drift.

| Subcommand | Purpose | Spec reference |
|---|---|---|
| `cairn compile <file.crn> --edition <e> --target <v>` | Compile a `.crn` source to NBT / schematic output for `(edition, version)` | [compilation §4.2](https://cairn.kage1020.com/spec/compilation/), [versioning-editions](https://cairn.kage1020.com/spec/versioning-editions/) |
| `cairn import <schematic> --mode raw\|l1` | Faithful transliteration of `.nbt` / `.litematic` / `.schem` / `.mcstructure` into raw-centric `.crn` | [ecosystem-interop §12.2](https://cairn.kage1020.com/spec/ecosystem-interop/) |
| `cairn info <file.crn> --editions java,bedrock` | Report registry compatibility window, semantic-sensitive members, and recommended test targets | [versioning-editions §10.5](https://cairn.kage1020.com/spec/versioning-editions/) |
| `cairn diff-blocks <schematic> <file.crn>` | Voxel XOR + state diff for the self-correction loop | [ecosystem-interop §12.2](https://cairn.kage1020.com/spec/ecosystem-interop/), [evaluation](https://cairn.kage1020.com/spec/evaluation/) |

## Targeting rules

Per [compilation §4.2](https://cairn.kage1020.com/spec/compilation/):

- `--edition` is **required** for any subcommand that emits voxels. The same `1.21` means different
  things on Java and Bedrock, and Java's DataVersion is unrelated to Bedrock's `block_version`.
- `--target` accepts either the legacy semver form (`1.21.4`) or a date-based string; both are
  resolved through DataVersion as the canonical ordering key
  ([versioning-editions §10.1](https://cairn.kage1020.com/spec/versioning-editions/)).

## License

Apache-2.0. See [LICENSE](../../LICENSE).