# CLI

The `masterbelt` command is the user-facing command line entry point.

Commands must read project configuration before running behavior that depends on user project settings.

Global options:

- `-c PATH` and `--config PATH` explicitly select the project configuration file.
- `--reporter FORMAT` selects the diagnostic reporter.
  - Supported formats are `text` and `json`.
  - `text` is the default and writes diagnostics to standard error.
  - `json` writes diagnostics to standard output by default.
  - JSON diagnostics can mix with command output when a command also writes primary output to standard output.
  - For machine-readable diagnostic output, use `json` with commands or modes that do not also emit primary output to standard output, such as `fmt --check` and `fmt --write`.
- Reporter shorthand:
  - `--text` is shorthand for `--reporter text`.
  - `--json` is shorthand for `--reporter json`.
  - `--text` and `--json` are mutually exclusive.
  - Reporter shorthand options conflict with an explicit `--reporter` value that selects a different format.

### Diagnostic Output

- Text diagnostics are written to standard error.
- JSON diagnostics are written to standard output.

## `fmt`

`masterbelt fmt` formats Masterbelt source files.

### Input

- Formatter inputs must be valid Masterbelt source text, including the language UTF-8 source text requirement.
- Invalid UTF-8 input fails formatting.
- Empty input is considered already formatted.
- When file paths are provided, the command formats each file independently.
- When no file path is provided, the command reads one source file from standard input and writes formatted source to standard output.

### Modes

- Without `--check` or `--write`, at most one file path may be provided.
- Formatting multiple files to standard output is invalid because the output would not preserve file boundaries.
- `--check` reports whether each input is already formatted.
- `--check` applies to file inputs and to standard input.
- `--check` must not write formatted source to files or standard output.
- `--check` fails when any input would change.
- `--write` updates file inputs in place.
- `--write` cannot be used when reading from standard input.
- `--check` and `--write` are mutually exclusive.
- The default mode writes formatted source to standard output.
- `--check` and `--write` suppress formatted source output.

### Configuration

- The formatter indentation option is resolved from project configuration for each file input.
- Standard input uses configuration discovered from the current working directory.

## `codegen`

`masterbelt codegen` runs every code generation target configured in the project's `masterbelt.yml`.

### Input

- The command reads the project configuration to discover the entrypoint and the configured target list.
- An entrypoint is required (see `tooling/configuration`); the command fails when `entry:` is missing.
- The command analyzes and lowers the entrypoint into the IR program model that targets consume. Future multi-file support follows once imports are implemented.

### Modes

- The command runs every configured target by default.
- The command does not read from standard input and does not write to standard output. Generated source is written to disk under each target's configured `out` directory.
- Each invocation overwrites any existing file at the same output path; the command does not perform incremental updates and does not delete files left over from previous runs.

### Output

- Output files are written into each target's `out` directory, creating parent directories as needed.
- The text reporter is silent on success.
- The JSON reporter writes an empty diagnostic envelope on success.

### Configuration

- A project configured with no targets is a no-op: the command exits with code 0 and writes no files.
- A target whose `kind` does not match any registered code generation target produces a diagnostic and the command fails.

## `export`

`masterbelt export` imports the project's master data, validates it, and writes the configured export artifacts.

### Validation

- Export imports each master's source records and applies each master's [filter](../masterdata/schema.md#filter-section), then runs each master's [validation](../masterdata/validation.md) rules over the post-filter records before writing any artifact.
- An `error`-severity validation failure (a failed `assert` whose resolved severity is `error`) blocks the entire export: no file is written. A `warning`-severity failure is reported but does not block the export.
- A validator-configuration error (`masterbelt.validation.config_unknown_master`, `masterbelt.validation.config_unknown_validator`, or `masterbelt.validation.config_invalid_severity`) is detected before validators run and likewise blocks the entire export.
- An import error blocks the export as well; export proceeds to validation and writing only when import succeeds.

### SQLite Index Inference

When the SQLite exporter is configured, a master's [`indexed scope`](../masterdata/schema.md#indexed-scopes) declarations drive secondary-index generation, defined in [export-sqlite.md](../masterdata/export-sqlite.md#secondary-indexes-from-indexed-scopes). Generating an index reports `masterbelt.scope.index_generated` (info) and a scope that cannot be fully inferred reports `masterbelt.scope.index_inference_failed` (warning); neither severity blocks the export.

## Exit Codes

- 0: the requested operation succeeds.
- 1: execution fails after command-line arguments are accepted, including diagnostics, unreadable inputs, unwritable outputs, invalid project configuration, or `fmt --check` detecting inputs that would change.
- 2: command-line arguments are invalid.