Command line

FLUX Simulation Engine: runs a FLUX bundle deterministically against the FLUID contract it references, and packs the evidence.

# start with a small working project
fluxsim init demo
cd demo
fluxsim run . --verify --ship -o out

# look up what an error code means
fluxsim explain FLX-3105

Commands

Command	What it does
`fluxsim init`	write a small working project into a new directory
`fluxsim validate`	validate a FLUX bundle
`fluxsim plan`	execute the loop once and record plan.json
`fluxsim apply`	apply a recorded plan and write its run directory
`fluxsim run`	plan + apply, with --verify/--ship sugar
`fluxsim verify`	golden regression + row conformance + RFC-04 + fidelity
`fluxsim ship`	the fidelity gate, then the evidence pack
`fluxsim replay`	re-execute a recorded plan; assert its digest
`fluxsim calibrate`	declared-scorecard calibration for a Playback
`fluxsim accuracy`	outcome-accuracy gate: register, score, record
`fluxsim gate`	RFC-04 enforcement gate: decide, conform
`fluxsim expr`	flux-expr/1: evaluate an expression, print an attribute model
`fluxsim describe`	self-describe this installation
`fluxsim plugins`	list installed vertical packs
`fluxsim explain`	print the catalog entry for one FLX-nnnn code, or list them all

Options every command accepts

Option	Description
`--version`	print the version and exit
`-j, --json`	emit machine-readable JSON

--json and -j may come before or after the command.

The JSON envelope

With --json every command prints one document of the same shape, so a caller never has to guess which command produced it or read stderr for the reason it failed:

{
  "stage": "validate",
  "exitCode": 0,
  "ok": true,
  "artifacts": {},
  "error": null
}

artifacts is the command's own output. error is null on success, otherwise {"code": "FLX-nnnn", "message": "..."}, where code is null for a failure with no catalogued code. A usage error is an envelope too, with exitCode 2.

Exit codes

Code	Meaning
`0`	The command ran and succeeded.
`1`	The command ran and failed. The message says why; a catalogued failure carries an `FLX-nnnn` code.
`2`	A usage error: the command line itself was wrong, so nothing ran.
`3`	`fluxsim gate decide` only: the request was decided, and the policy said no.

Environment

Variable	Effect
`FLUX_ZONE`	The run's declared zone for sovereignty checks, used when `--zone` is not given.
`FLUX_DEBUG`	Any non-empty value prints the traceback of an unexpected failure.
`FLUX_NO_PROGRESS`	Any non-empty value silences the progress lines and the `next:` hints that a terminal otherwise gets on stderr.

All error codes