# Command Lines — Overview

**As of:** 2026-10-05

Every command this project provides, in one place. This is the quick reference;
for what each tool derives, how, and the full description of every switch, see
[`Python_Scripts.md`](Python_Scripts.md).

All commands live in `bin/` as a `.bat` (Windows) / `.sh` (Linux/macOS) pair.
Examples below use the Windows form; on Linux/macOS replace `bin\x.bat` with
`bash bin/x.sh` (or `source bin/x.sh` where noted).

## 1. Environment commands

These set up or enter the environment. They never run a Python tool.

| Command | Purpose |
|---|---|
| `bin\setenv.bat` / `source bin/setenv.sh` | Sets `SPS_SKEL` and `SKEL_BIN/LIB/CFG/DATA/DOC/LOG/RESULTS/EXAMPLES/TESTS`, prepends `SKEL_LIB` to `PYTHONPATH`, creates missing folders. Windows: `--keep-open` pauses at the end. |
| `bin\install_py.bat` / `bash bin/install_py.sh` | One-time: creates `.venv` and installs `requirements.txt`. Does nothing if `.venv` already exists. |
| `bin\activate_venv.bat` / `source bin/activate_venv.sh` | Each session: sets the environment and activates `.venv` (error if missing — run `install_py` first). |
| `bin\get_cmd.bat` / `bash bin/get_cmd.sh` | Opens a new shell with the environment variables set. |

## 2. Pipeline tools

The five CLI tools, in pipeline order. Each wrapper sets the environment,
activates `.venv` if present and runs `lib/<name>.py` with all arguments passed
through. Every tool accepts `--help`.

```
CSV ─► material_flow ─► tro_flow --json ─► <name>_tro.json ─► scl_skeleton ─► <name>_FB_Main.scl
                           │                (model.py)          (validates)
                           └─► tro_annotate (+ DXF) ─► <name>_annotated.dxf   viewer only

parked: tro_extract (DXF → JSON), see 2.4
```

Shared conventions:

- Input names (`--file`, `--dxf`) are a bare filename resolved against
  `%SKEL_DATA%`, or a full path. `scl_skeleton` (and the parked `tro_extract`)
  look up their input in `%SKEL_RESULTS%` instead (it is the output of the
  previous step).
- All output goes to `%SKEL_RESULTS%`.
- `--tosvg` needs Graphviz `dot` (`neato` with `--use-cords`) on `PATH`, or
  `GRAPHVIZ_DOT` pointing at `dot`.

### 2.1 `material_flow` — material-flow graph of the mechanical objects

Input: CSV export. Details: [`Python_Scripts.md` §3](Python_Scripts.md#3-material_flowpy--material-flow-graph-of-the-mechanical-layout).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input. |
| `--tosvg` | — | off | Also render `.svg` via Graphviz. |
| `--use-cords` / `--use-coords` | — | off | Place nodes at plant coordinates (`neato -n`). Only with `--tosvg`. |
| `--doc` | — | off | Write Markdown report `<name>_material_flow.md`. |
| `--connect` | — | off | Write topology as `<name>_connect.ini`. |
| `--show-bbs` | `flow` \| `all` | `flow` if given without value | Write top-down view `<name>_bbs.svg` (no Graphviz). `all` also draws VF/GF chain detail rows. |
| `--show-kx` | — | off | Only with `--show-bbs`: draw connection points K1–K4. |
| `--track` | — | off | Write fine-grained track graph `<name>_track.dot` (`.svg` with `--tosvg`). |
| `--chain-graph` | — | off | Write chain/layout plan of the coarse objects (`<name>_chain.svg` / `.dot`). |
| `--graphtype` | `coarsebox` \| `compound` \| `subgraph` | `coarsebox` | Only with `--chain-graph`: rendering method. |

Exit codes: `0` ok · `1` input/CLI error · `2` SVG rendering failed.

```bat
bin\material_flow.bat --file mubea.csv --tosvg --use-cords --doc
bin\material_flow.bat --file HundM05.csv --show-bbs all --show-kx
bin\material_flow.bat --file HundM05.csv --chain-graph --graphtype subgraph --tosvg
```

### 2.2 `tro_flow` — derive and draw the TROs

Input: CSV export. Details: [`Python_Scripts.md` §4](Python_Scripts.md#4-tro_flowpy--derive-and-draw-the-tros).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input. |
| `--tosvg` | — | off | Also render the TRO flow diagram as `.svg`. |
| `--use-cords` / `--use-coords` | — | off | Place TROs at plant coordinates (`neato -n`). Only with `--tosvg`. |
| `--true-scale` | — | off | Only with `--use-cords`: draw to scale (default shortens empty stretches > 1500 mm). |
| `--doc` | — | off | Write Markdown report `<name>_tro_doc.md`. |
| `--connect` | — | off | Write TRO topology as `<name>_tro_connect.ini`. |
| `--json` | — | off | Write the TRO-JSON `<name>_tro.json` (model `lib/model.py`) — input for `scl_skeleton`. |

Exit codes: `0` ok · `1` input/CLI error · `2` SVG rendering failed ·
`3` TRO validation errors (`<name>_tro_errors.md` written).

```bat
bin\tro_flow.bat --file mubea.csv --tosvg --use-cords --doc
bin\tro_flow.bat --file mubea.csv --json
```

### 2.3 `tro_annotate` — burn the TROs into a copy of the drawing

Viewer only: shows the same TROs as `tro_flow` in the drawing for a visual
check; the drawing is not read back as data.
Input: CSV export + original BricsCAD DXF. The original is never modified.
Details: [`Python_Scripts.md` §5](Python_Scripts.md#5-tro_annotatepy--burn-the-tros-into-a-copy-of-the-cad-drawing).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input. |
| `--dxf` | `NAME` | — | Original drawing (DXF). Required unless `--emit-lisp` is used alone. |
| `--out` | `NAME` | `<csv-stem>_annotated.dxf` | Output filename. |
| `--flow` | — | off | Draw flow arrows between TROs. |
| `--fb` | — | off | Show the Siemens FB block name on the marker. |
| `--legend` | — | off | Draw a color-group legend. |
| `--marker-size` | `MM` | `300.0` | Marker radius in mm. |
| `--text-height` | `MM` | `220.0` | Text height in mm. |
| `--offset` | `DX,DY` | — | Set the CSV↔DXF offset by hand (`0,0` for dxfmakros drawings). |
| `--re-register` | — | off | Re-derive the offset even if a cached one exists in `%SKEL_CFG%`. |
| `--check` | — | off | Dry run: analyze and report, write nothing. |
| `--emit-lisp` | — | off | Regenerate `cad/tro_types.lsp` (or under `%DXFM_LISP%`) and exit. |

Exit codes: `0` ok · `1` input/CLI error · `4` coordinate registration not
provable — use `--offset`.

```bat
bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend
bin\tro_annotate.bat --file mubea.csv --dxf Mubea.dxf --offset 0,0 --check
bin\tro_annotate.bat --emit-lisp
```

### 2.4 `tro_extract` — read the TROs back out of the drawing into JSON

**Parked** — kept, but not part of the main path. Its JSON (schema
`sps_skel-tro-extract-v1`) is rejected by `scl_skeleton`; use
`tro_flow --json` instead.

Input: the (possibly hand-edited) annotated DXF only, never the CSV.
Details: [`Python_Scripts.md` §5a](Python_Scripts.md#5a-tro_extractpy--read-the-tros-back-out-of-the-drawing-into-json).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--dxf` | `NAME` | `export_annotated.dxf` | Annotated drawing (looked up in `%SKEL_RESULTS%`). |
| `--out` | `NAME` | `<drawing>_tro.json` | Output JSON filename. |

Exit codes: `0` ok · `1` input/CLI error · `2` no TRO markers in the drawing.

```bat
bin\tro_extract.bat --dxf mubea_annotated.dxf
```

### 2.5 `scl_skeleton` — generate the `FB_Main` SCL skeleton

Input: TRO-JSON from `tro_flow --json`, validated against `lib/model.py` — a
wrong or renamed key stops the run (exit `1`) instead of producing SCL. Output
is a skeleton with `TODO(E-Planung)` gaps, not a compilable program.
Details: [`Python_Scripts.md` §5b](Python_Scripts.md#5b-scl_skeletonpy--generate-the-fb_main-skeleton-as-scl).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--json` | `NAME` | `export_tro.json` | TRO-JSON input (looked up in `%SKEL_RESULTS%`). |
| `--out` | `NAME` | `<source>_FB_Main.scl` | Output SCL filename. |
| `--start` | `TRO` | — | TRO where the REGION order begins. Only needed while the flow is a closed loop without a loading/unloading station (`SYSn`). |

Exit codes: `0` ok · `1` input/CLI error or JSON does not match the model.

```bat
bin\scl_skeleton.bat --json mubea_tro.json
bin\scl_skeleton.bat --json mubea_tro.json --start TRO01
```

## 3. End-to-end example

```bat
bin\activate_venv.bat
bin\material_flow.bat --file mubea.csv --tosvg --doc
bin\tro_flow.bat      --file mubea.csv --tosvg --use-cords --doc --json
bin\scl_skeleton.bat  --json mubea_tro.json
REM   optional, for a visual check in BricsCAD:
bin\tro_annotate.bat  --file mubea.csv --dxf Mubea.dxf --flow --legend
```

Tests: `python -m pytest tests/` (with `.venv` active).

## 4. Documentation tooling (not part of the pipeline)

| Command | Purpose |
|---|---|
| `py doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py` | Regenerates the per-type SVGs, the edge legend and the UH01–UH05 topology graphs for `TRO_Katalog.md` from `doc/TRO_Katalog/connect.ini`. No switches, no `bin/` wrapper. Needs Graphviz `dot`. |

The libraries `lib/tro_catalog.py`, `lib/model.py`, `lib/dxf_registration.py`
and `lib/tro_overrides.py` have no command line of their own.