3.3 KiB
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.
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 and the language contract.