---
audience: engineers
summary: "Every scaicore subcommand \u2014 compile, check, run, inspect \u2014 with\
  \ flags, output, and exit codes."
title: CLI
path: reference/cli
status: published
---

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.

```
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.

```
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.

```
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.

```
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.