67 lines
3.3 KiB
Markdown
67 lines
3.3 KiB
Markdown
# 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).
|