ARCADIA-Studio/docs/source-cli.md

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.

Read-only mixed source8 checking

arcadia check-mixed path/to/main.arcadia --json

Use check-mixed for source8 containing ordinary declarations and typed analysis (quantity kinds, units, calculations, properties, checks and cases). Every project, ordinary declaration, typed definition and scoped parameter must have an explicit UUID. This command does not migrate older headers, allocate UUIDs, format, preview edits or save. --write is a usage error. Existing check, lint, stabilize and rename-alias retain their ordinary-source behavior.

The loader discovers actual includes with the source grammar and existing portable-path, regular-file, bounded-read and pending-journal checks. It captures original bytes, runs a bounded discovery syntax pass, then checks the complete borrowed bundle in a separate bounded verification pass. A discovery diagnostic prevents complete verification; the first mixed syntax/work failure stops further discovery parsing. Both passes derive limits from the same CLI policy; numeric work is bounded per pass, not once across the whole command. Logical producer limits are not a bound on all allocations or process memory.

The format-1 JSON envelope uses operation check-mixed, status checked or invalid for completed source checking, and existing rejected for direct disk errors. changes is empty, written is false, identities_to_stabilize is zero, migration is null and notes is empty. Located diagnostics refer to original input bytes, with half-open UTF-8 byte spans and one-based Unicode-scalar line/column coordinates. Direct filesystem failures use the existing operation coordinate space. Engineering warnings permit exit 0; invalid source/semantics exit 1, usage exits 2, and disk/path/missing-file/pending-journal failures exit 3. Invalid UTF-8 discovery diagnostics retain the existing source-error exit 1.

Human output goes to stderr and ends with checked: mixed source8 check; no files changed on success, after any warnings. No source bytes or directory entries are written, and pending saves are never recovered implicitly. Checking captured bytes does not establish an atomic multi-file snapshot against concurrent writers. This command provides validation only; mixed editing, adoption, GUI and history integration remain outside this interface.