railiance-cluster/docs/railiance-run-command.md

Railiance Run Command

bin/railiance run executes Stage 1 local validation for a repository that contains railiance/app.toml.

The command is intentionally local and conservative:

• reads railiance/app.toml using the railiance.app.v1 contract;
• runs [stages.stage1].commands from the app directory;
• evaluates Stage 1 check ids listed in [stages.stage1].checks when they can be checked locally;
• emits a machine-readable railiance.run-result.v1 JSON result;
• records command references, exit codes, durations, and output byte counts, but not shell text or command stdout/stderr content;
• strips credentials, query strings, and fragments from URLs before reporting HTTP check results.

Usage

bin/railiance run /path/to/app-or-overlay --pretty
bin/railiance run . --json-out .railiance/stage1-result.json

The process exits 0 only when all Stage 1 commands and required checks pass. Optional checks may be skipped without failing the run. For example, an optional local health endpoint can be declared before a local server command exists.

Supported Local Checks

• command: runs the check run command in the app directory.
• http: calls the declared URL and compares the HTTP status.
• helm: runs helm template when Helm is installed. Required Helm checks fail if Helm is unavailable; optional Helm checks are skipped.

Other check types are reported as skipped or failed depending on whether the check is required. Stage 2 and Stage 3 checks are never executed by railiance run.

Result Shape

The JSON result includes:

• app identity and source revision;
• contract path and app directory;
• command/check status summaries using contract references instead of raw shell commands;
• expected evidence labels from Stage 1;
• timing and exit status metadata.

The result is suitable for later promotion gates and State Hub progress notes, without embedding secrets or verbose logs.