CLI

The scaicore command is the primary developer interface to the toolchain. It has four subcommands: compile, check, run, inspect. All four take a .scaicore source file as their first positional argument; run and inspect require a file (not a directory), while compile and check accept either a file or a directory containing exactly one .scaicore file.

Exit codes are uniform across subcommands:

Code	Meaning
`0`	Success.
`1`	The operation ran but reported errors (compile diagnostics, runtime failure, etc.).
`2`	The operation could not start (source path missing, no `.scaicore` files in the directory).

compile#

Compile a .scaicore source file into a .scaicore-ir bundle.

text

1	`scaicore compile <source> [--output PATH] [--emit-ir] [--emit-manifest] [--debug] [--strict]`

Runs the full pipeline — lex, parse, resolve, type-check, build IR, verify — and writes the serialized IR bundle to disk. If --output is omitted, the bundle lands at build/<core-name>.scaicore-ir.

Options.

--output, -o PATH — write the bundle to a specific path.
--emit-ir — print a human-readable summary of the IR to stdout instead of writing a bundle. Useful for inspecting block structure.
--emit-manifest — print the CoreManifest as JSON to stdout. Useful for plumbing into deployment automation.
--debug — include @debug blocks in the output bundle. Off by default; @debug blocks compile away in production builds.
--strict — treat warnings as errors.

Output. On success, prints ✓ Compiled <name> v<version> (N flows, M types, …) and the bundle path with its size. On failure, prints error[Exxx]: <message> for each diagnostic and exits with code 1.

check#

Run the compile pipeline without writing a bundle. This is the fastest way to validate source syntax, types, and verifier invariants.

text

1	`scaicore check <source> [--strict]`

Options.

--strict — treat warnings as errors.

Output. On success, prints ✓ <name> v<version> — all checks passed (N flows, …). On failure, prints each diagnostic and exits with code 1. No files are written.

run#

Compile a .scaicore source file in-memory and execute a named flow.

text

1	`scaicore run <source> [--flow NAME] [--input JSON] [--identity SPEC] [--trigger TYPE] [--verbose]`

Options.

--flow, -f NAME — flow to execute. If omitted, the first flow in the source is used.
--input, -i JSON — JSON input data for the flow. Use @path/to/file.json to load from a file. Maps onto the flow's input parameters.
--identity SPEC — identity context for the invocation. Formats: dev:<name> (developer), sa:<name> (service account), or none.
--trigger TYPE — trigger type recorded on the invocation. Defaults to direct. Other values: webhook, schedule, api, event.
--verbose, -v — print recorded side effects after the run.

Output. Prints one of:

Completed in X.XXXs followed by the JSON-encoded output value.
Failed: <message> — runtime error; exits with code 1.
Suspended at checkpoint followed by the checkpoint id — execution paused waiting on a human response.

inspect#

Inspect a Core's manifest — flows, triggers, required plugins, config schema — without running anything.

text

1	`scaicore inspect <source> [--flows] [--triggers] [--plugins] [--config-schema] [--full]`

With no flags, prints all sections in a compact form. The flag-specific options narrow the output to just that section. --full prints the entire manifest as JSON.

Options.

--flows — list flow signatures (name(params): return_type).
--triggers — list declared triggers and their target flows.
--plugins — list required plugin packages.
--config-schema — list config parameters and whether they're required.
--full — print the full manifest as JSON.

This is the recommended way to read what a deployable Core requires from its host before invoking it.