#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, then runs each master's validation 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 declarations drive secondary-index generation, defined in export-sqlite.md. 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.