CLI workflows

Use this guide when you want a repeatable command sequence. It assumes pyfcstm is already installed; if not, start with Install pyfcstm. For exact options and failure boundaries, use CLI reference.

Concrete sample used below

The examples on this page use the checked-in quick-start source docs/source/tutorials/quick_start/traffic_light.fcstm when a real input is needed. Replace that path with your own machine file in project scripts.

Run one command first to prove that the CLI, the parser, and the model importer all see the same source:

pyfcstm inspect -i docs/source/tutorials/quick_start/traffic_light.fcstm

Expected success signal:

[OK] FCSTM Inspect Report: docs/source/tutorials/quick_start/traffic_light.fcstm
root: TrafficLight
states: 4 total / 3 leaf
transitions: 4
diagnostics: 0 errors / 0 warnings / 0 infos

If the command fails before the summary, fix that layer before trying simulation, generation, or visualization. Unreadable files, parse errors, and model validation errors are earlier-layer problems; renderer and template changes cannot repair them.

Choose the right command first

Command selection
Goal	Command	Main output	Follow-up reference
Run the model without generated code	`simulate`	active state and variable trace	Simulation reference
Read model facts and diagnostics	`inspect`	human, JSON, or LLM-oriented report	Inspect report reference
Generate target-language files	`generate`	output directory	Built-in templates reference
Export diagram source	`plantuml`	`.puml` text	Visualization options reference
Render diagram artifacts	`visualize`	`.png`, `.svg`, or `.pdf`	Visualization options reference

Core workflow acceptance cards

Use this table when turning commands into project automation. Each row gives the minimum evidence that the step succeeded and the first thing to inspect when it does not.

CLI task acceptance cards
Task	Copyable command	Success signal	File side effect	First troubleshooting step
Simulate a short path.	`pyfcstm simulate -i docs/source/tutorials/quick_start/traffic_light.fcstm -e "current; cycle; current"`	Output includes `Current State: TrafficLight.Red` after the cycle.	None unless stdout is redirected.	Run `inspect` first; if inspect is clean, check batch command spelling and event names.
Export machine facts.	`pyfcstm inspect -i docs/source/tutorials/quick_start/traffic_light.fcstm --format json -o /tmp/traffic.inspect.json`	JSON contains `"root_state_path": "TrafficLight"` and an empty `diagnostics` list.	Writes the requested report file.	Check `--format` spelling and verify-policy options before assuming the model is wrong.
Generate Python files.	`pyfcstm generate -i docs/source/tutorials/quick_start/traffic_light.fcstm --template python -o /tmp/traffic-python --clear`	Output directory contains generated Python runtime files and generated README guidance.	Replaces the output directory when `--clear` is present.	Confirm exactly one of `--template` or `--template-dir` is used and that the output directory is disposable.
Export PlantUML source.	`pyfcstm plantuml -i docs/source/tutorials/quick_start/traffic_light.fcstm -o /tmp/traffic.puml`	The file starts with `@startuml` and contains `state "TrafficLight"`.	Writes only the requested `.puml` file.	If this fails, debug DSL/model errors; no renderer is involved.
Check a renderer.	`pyfcstm visualize --check --renderer auto`	Reports at least one usable renderer, or a clear backend error.	No DSL file is read and no diagram file is written.	For local failures, provide `--plantuml-jar` or `PLANTUML_JAR`; for remote failures, check the remote host.
Render a diagram.	`pyfcstm visualize -i docs/source/tutorials/quick_start/traffic_light.fcstm -t svg -o /tmp/traffic.svg --no-open`	The requested SVG exists and is non-empty.	Writes the rendered artifact and may use renderer cache directories.	Run `plantuml` first to separate source-export failures from renderer failures.

Inspect command help

Start with top-level help, then inspect the subcommand you intend to run:

pyfcstm --help
pyfcstm inspect --help
pyfcstm generate --help

Use help output as a quick sanity check for the environment. If pyfcstm is not found, try the same environment through python -m pyfcstm --help and then return to Install pyfcstm.

Run a short simulation

Use batch mode for transcripts that belong in documentation, CI logs, or bug reports:

pyfcstm simulate -i machine.fcstm -e "current; cycle; current"

Use interactive mode when you are exploring manually:

pyfcstm simulate -i machine.fcstm

Practical checks:

Start with current so the transcript records the initial active path.
Use explicit event names in batch scripts, for example cycle Start.
Use hot start only when you can provide every required variable value.
Do not use simulation as proof that generated target code is correct; use it as the reference behavior to compare against generated-runtime tests.

Export an inspect report

Human output is useful while editing:

pyfcstm inspect -i machine.fcstm

Use full JSON when a script will consume metrics, diagnostics, or model facts:

pyfcstm inspect -i machine.fcstm --format json -o machine.inspect.json

Use an LLM-oriented format when you plan to paste the report into a repair prompt:

pyfcstm inspect -i machine.fcstm --format llm-md -o machine.inspect.md

For CI-style checks, keep the command explicit and bounded:

pyfcstm inspect -i machine.fcstm \
  --format json \
  --enable-verify \
  --smt-timeout-ms 2000 \
  -o machine.inspect.json

If this fails before reading the model, check the verify-policy options. Inspect parses some higher-cost taxonomy labels only to report that automatic inspect runs are not allowed to use them.

Generate code from a built-in template

Prefer packaged built-in templates for normal users:

pyfcstm generate -i machine.fcstm --template python -o generated/python --clear

Use a custom template directory only when you intentionally maintain that template:

pyfcstm generate -i machine.fcstm -t ./templates/my_target -o generated/my_target --clear

Generation checklist:

Keep the DSL source and generation command together in project notes or build rules.
Use --clear only for an output directory that is safe to replace.
Review generated files before committing them.
If generated outputs are rebuilt on demand, put the generated directory in .gitignore instead of committing stale artifacts.
Use the generated README as the next entry point for runtime-specific integration and smoke checks.

Export PlantUML source

Use plantuml when you want deterministic source that can be reviewed, committed, or rendered by another tool:

pyfcstm plantuml -i machine.fcstm -o machine.puml

Choose a detail level before adding overrides:

pyfcstm plantuml -i machine.fcstm -l full -o machine.full.puml

Add narrow configuration overrides only when the diagram needs them:

pyfcstm plantuml -i machine.fcstm \
  -c show_events=true \
  -c max_depth=2 \
  -o machine.focused.puml

Render a diagram artifact

Use visualize --check first when the renderer environment is uncertain:

pyfcstm visualize --check --renderer auto

Render without opening a viewer in CI or headless environments:

pyfcstm visualize -i machine.fcstm -t svg -o machine.svg --no-open

Prefer local rendering for private diagrams:

pyfcstm visualize -i machine.fcstm --renderer local -p ./plantuml.jar --no-open

Use remote rendering only when the generated PlantUML source is allowed to be sent to the configured service:

pyfcstm visualize -i machine.fcstm --renderer remote --no-open

Make command runs reproducible

A repository that depends on pyfcstm commands should make the input/output relationship obvious:

Put source machines under a stable directory such as machines/ or src/machines/.
Name generated output directories by target, for example generated/python or generated/c_poll.
Record command lines in a Makefile, CI job, or project README.
Keep inspection reports and diagrams either clearly generated or clearly committed as review artifacts.
Use plantuml source export when a rendered image is not necessary.
Use visualize --no-open in scripts so GUI availability does not affect the build result.

Troubleshoot by layer

Troubleshooting route
Symptom	First command	Next page
`pyfcstm` command is missing	`python -m pyfcstm --help`	Install pyfcstm
DSL does not parse	`pyfcstm inspect -i machine.fcstm`	DSL reference
Model parses but behavior is surprising	`pyfcstm simulate -i machine.fcstm -e "current; cycle; current"`	Execution semantics explanation
Diagnostics need interpretation	`pyfcstm inspect -i machine.fcstm --format json`	Diagnostics code reference
Generation fails	`pyfcstm generate ... --template python`	Built-in templates reference
Rendering fails	`pyfcstm visualize --check --renderer auto`	Visualization options reference

Worked command examples with expected signals

Use the examples below as copyable patterns. They intentionally show only short output excerpts; full command output may include richer terminal formatting.

Command inputs and success signals
Task	Starting input	Command	Success signal	File side effect
Simulate one cold-entry cycle.	`traffic_light.fcstm` from the quick-start tutorial.	`pyfcstm simulate -i traffic_light.fcstm -e "current; cycle; current"`	Transcript contains `Cycle: 0` followed by `Cycle: 1` and `Current State: TrafficLight.Red`.	None.
Export a human inspect report.	Any parseable `.fcstm` file.	`pyfcstm inspect -i traffic_light.fcstm`	Output begins with `[OK] FCSTM Inspect Report` and ends with `No diagnostics.` for a clean model.	None.
Export JSON inspect data.	Any parseable `.fcstm` file.	`pyfcstm inspect -i traffic_light.fcstm --format json -o traffic_light.inspect.json`	JSON contains `metrics` and `diagnostics` keys.	Writes `traffic_light.inspect.json`.
Generate the Python built-in template.	Any parseable `.fcstm` file.	`pyfcstm generate -i traffic_light.fcstm --template python -o generated/python --clear`	Output directory contains `machine.py`, `README.md`, and `README_zh.md`.	Clears and rewrites `generated/python`.
Export PlantUML source.	Any parseable `.fcstm` file.	`pyfcstm plantuml -i traffic_light.fcstm -o traffic_light.puml`	File begins with `@startuml` and includes the root state.	Writes `traffic_light.puml`.
Check visualization backend.	No DSL input required.	`pyfcstm visualize --check --renderer auto`	Output reports local and/or remote renderer status.	None.
Render an SVG artifact.	Any parseable `.fcstm` file and a working renderer.	`pyfcstm visualize -i traffic_light.fcstm -t svg -o traffic_light.svg --no-open`	Command reports the renderer and output path on success.	Writes `traffic_light.svg`.

Short output excerpts

Simulation batch output should look like this, with formatting possibly changing by terminal:

>>> current
Cycle: 0
Current State: TrafficLight
Variables:
  timer = 0
>>> cycle
Cycle: 1
Current State: TrafficLight.Red

Inspect human output for the same clean model is intentionally compact:

[OK] FCSTM Inspect Report: traffic_light.fcstm
Summary
  status: ok
  root: TrafficLight
  states: 4 total / 3 leaf
  transitions: 4
  variables: 1
  diagnostics: 0 errors / 0 warnings / 0 infos

No diagnostics.

A generated Python output directory should have this minimum shape:

README.md
README_zh.md
machine.py

PlantUML source begins as text, not as an image:

@startuml
hide empty description
skinparam state {
  BackgroundColor<<pseudo>> LightGray
}

Failure probes

Use these probes when a workflow fails and you need to locate the layer quickly:

Failure probes
Probe	Command	Expected failure signal	Meaning
Missing input option.	`pyfcstm inspect`	`Missing option '-i' / '--input-code'`.	Click did not reach DSL parsing.
Invalid inspect format.	`pyfcstm inspect -i traffic_light.fcstm --format xml`	Click reports allowed choices.	Fix command syntax before debugging the model.
Visualization suffix mismatch.	`pyfcstm visualize -i traffic_light.fcstm -o traffic_light.svg -t png --no-open`	Output says `Output file suffix '.svg' does not match render type 'png'.`	Fix output naming before debugging PlantUML.
Simulator command-layer failure.	`pyfcstm simulate -i traffic_light.fcstm -e "rewind"`	Transcript says `Unknown command: rewind` while batch mode still exits with status `0`.	Treat the transcript as the failure signal and fix the simulator command script.
Renderer availability.	`pyfcstm visualize --check --renderer local`	Reports missing Java, PlantUML jar, or backend failure when local rendering is unavailable.	Configure local renderer or switch to an allowed remote renderer.

End-to-end acceptance cards

Use these cards when a project README, CI job, or bug report needs more than a single command. Each card connects the command sequence to an acceptance signal and a first repair path.

Workflow acceptance cards
Workflow	Commands	Accept when	Repair first
Reproduce a user’s current state	`pyfcstm simulate -i machine.fcstm -e "current; cycle Start; current"`.	The transcript names the starting active path, the cycle count changes, and variables are visible.	If the event has no effect, inspect whether the event scope and source state match the model.
Hand a model to an LLM for repair	`pyfcstm inspect -i machine.fcstm --format llm-md -o machine.inspect.md`.	The Markdown report includes status, metrics, diagnostics, source excerpts, and suggested repair facts.	If the report is empty or lacks diagnostics, rerun with human format to confirm the file being inspected.
Capture a machine-readable regression artifact	`pyfcstm inspect -i machine.fcstm --format json -o reports/machine.inspect.json`.	JSON parses successfully and contains metrics plus diagnostics arrays.	If a suffix warning appears, rename the target so humans do not confuse the format.
Refresh generated Python code	`pyfcstm generate -i machine.fcstm --template python -o generated/python --clear`.	`machine.py`, `README.md`, and `README_zh.md` exist, and the target directory contains only expected generated files.	If stale files remain, check that `--clear` targeted the generated directory you inspected.
Produce reviewable diagram source	`pyfcstm plantuml -i machine.fcstm -l normal -o diagrams/machine.puml`.	The file is text, begins with `@startuml`, and can be diffed in code review.	If reviewers expected an image, either render with `visualize` or state that source review is intentional.
Produce a rendered documentation image	`pyfcstm visualize -i machine.fcstm -t svg -o docs/_static/machine.svg --no-open`.	The SVG exists and a visual inspection confirms labels are readable.	If rendering fails, run `visualize --check` before changing diagram options.

Next steps

Generation tasks covers generated-runtime tasks.
Inspect tasks covers inspect workflows in more depth.
Visualization tasks covers diagram export choices.