# Source CLI

Use `arcadia` to check or update local `.arcadia` projects without opening Studio
or starting a server. Pass the entry file explicitly; its relative include paths
resolve from their containing source files.

Build with `cargo build --locked -p oa-cli --bin arcadia`. The resulting command
is `target/debug/arcadia.exe` on Windows or `target/debug/arcadia` on Linux unless
your Cargo configuration chooses another target directory. A workspace release
build also includes it. Use the platform's usual executable path prefix when
running these examples.

```sh
arcadia check project.arcadia
arcadia check project.arcadia --json
arcadia stabilize project.arcadia
arcadia stabilize project.arcadia --write
arcadia rename-alias project.arcadia old_alias new_alias
arcadia rename-alias project.arcadia old_alias new_alias --write --json
```

`lint` is an alias for `check`. Checks accept incomplete engineering models with
warnings; syntax errors and structural violations fail. Located diagnostics
refer to the named file and coordinate space. Line and column numbers are
one-based and columns count Unicode scalar values; byte ranges are half-open
UTF-8 offsets.

`stabilize` previews missing persistent identities and any supported source
migration. `rename-alias` changes one existing global alias and its typed
references while preserving comments, strings and unrelated source. Pass alias
names without `@`. The command does not rename an element's display name.

Both editing commands preview by default. Human output writes unified file
diffs to stdout and diagnostics to stderr. `--json` writes one versioned report
with diagnostics, migration information, exact before/after text for every
changed file, diffs and the write result. Unchanged files are not included in
that report. They are still checked for conflicts before a write.

Add `--write` to save the candidate prepared by that invocation. Even an empty
diff checks the captured files and pending-save state before returning. A failed
write reports `written: false` and retains its proposed diff. This does not
guarantee rollback; the reported conflict or recovery outcome determines the
next step. A pending save
requires explicit recovery through the existing project recovery workflow;
the CLI does not recover it automatically.

Missing IDs in a separate earlier preview remain provisional. A later command
may allocate different IDs until you save them. This CLI does not persist a
review plan for later application. It does not canonicalize the whole project
or delete detached files. Source versions 3–7 use the core's supported migration
rules; invalid source is not rewritten.

| Exit code | Meaning |
| --- | --- |
| 0 | Valid check or successful preview/write; warnings may remain |
| 1 | Invalid source or refused semantic alias change |
| 2 | Invalid command arguments |
| 3 | File/path, conflict, pending-save or output failure |

Admission bounds match the desktop: 256 files, include depth 32, 1024 include
edges, 64 MiB total UTF-8, 100,000 graph objects, 250,000 records and 500,000
ordered references. `arcadia --help` lists the commands and bounds. These limits
are not a claim of interactive performance at the maximum project size.

For the notation itself, start with [the text-first examples](../examples/text-first/README.md)
and the [language contract](language.rst).