Command families

Family Purpose
fastsim config ... validate, expand, explain, diff, lock, and verify-lock
fastsim plugins ... list/inspect compiled instances without import, or diagnose selected factories
fastsim run ... launch an Application from a compiled Plan
fastsim outputs ... discover, inspect, open, or clean artifacts under a trusted root
fastsim settings ... manage strictly optional user settings

Automation and CI should consume --json plus process exit status. Human-oriented colored output is not a protocol.

bash
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.robots.arm.use
fastsim config lock run.yaml --output run.lock --json

plugins list and plugins inspect read compiled metadata without importing plugin code. plugins diagnose imports only factories selected by the Run to isolate packaging, entry-point, or contract failures.

Output operations remain inside the resolved trusted root. Inspect before cleanup, and never use a user home, project root, or unresolved environment variable as a recursive target. Staging, validation, atomic publication, and failure cleanup protect output integrity.

See Recording, replay, and outputs and Configuration.

Automation contract

CI should prefer --json and process exit codes. Human rich/plain output may evolve and is not a protocol. Save validation bodies, Plan/Lock digests, installed distribution versions, final Application state, and output receipts with the run evidence.

Configuration validation, Lock verification, and plugin metadata inspection run before a real Provider gate. Failed commands retain the complete invocation, structured response, version information, and exit status.

Bounded inspection and cleanup

Outputs pass staging, validation and atomic publication before offline consumption
Outputs pass staging, validation and atomic publication before offline consumptionEnlarge diagram

Ordinary outputs list reads bounded metadata; --verify validates the current page; inspect, verify, and open load the separately installed Viewer only when requested. Relative targets cannot escape the resolved output root, symlinks and special files are rejected, and a basename must match uniquely.

Safe cleanup. Resolve and inspect the output root first. remove targets one explicit ordinary file; clean only removes sufficiently old .incomplete transaction files and never treats complete FSR files as temporary. Both require explicit confirmation. Do not bypass these boundaries with shell globs or use a home/project root as a broad output root.