Terminal Commands (PCS CLI)¶
The repo-local pcs command is the preferred developer entry point. Run commands from the repository root unless noted otherwise.
Use the friendly CLI first
Prefer pcs ... commands for daily work. The lower-level scripts in tools/tia-openness remain available for troubleshooting and automation.
Command Map¶
This quick reference is grouped by command family. The detailed sections below explain when to use each command and which options matter.
Setup And Configuration¶
| Task | Command |
|---|---|
| First-time machine tool setup | .\pcs.cmd install tools |
| Check tools without changing the machine | .\pcs.cmd install tools --check-only |
| Install supported missing tools without extra prompts | .\pcs.cmd install tools --yes |
| Initialize repo-local environment | pcs init |
| Show resolved project settings | pcs config show |
Source Creation And Tool Build¶
| Task | Command |
|---|---|
| Create a block scaffold in the root | pcs new block FB_MyNewBlock |
| Create a block scaffold in a subsystem | pcs new block 06_ALARMS/FB_AlarmRouting |
| Build the Openness CLI | pcs build |
| Build against a specific TIA version | pcs build tia-version=V20 |
Project Discovery¶
| Task | Command |
|---|---|
| List configured PLCs without opening TIA | pcs list plcs configured |
| List PLCs from the TIA project | pcs list plcs |
List blocks in tia/exports |
pcs list blocks |
Deployment¶
| Task | Command |
|---|---|
| Deploy all configured sources | pcs deploy |
| Deploy to one PLC | pcs deploy plcs=PLC_1 |
| Deploy selected blocks | pcs deploy plcs=PLC_1 blocks=FB_AlarmRouting,FB_AlarmDelay |
| Deploy one folder | pcs deploy plcs=PLC_1 folder=06_ALARMS |
| Deploy without compile | pcs deploy plcs=PLC_1 blocks=FB_AlarmRouting no-compile |
| Preview a deploy | pcs deploy plcs=PLC_1 folder=06_ALARMS dry-run no-compile |
| Build Openness CLI before deploy | pcs deploy build |
TIA / Repository Sync¶
| Task | Command |
|---|---|
| Show repository sync status | pcs sync status |
| Show sync status as JSON | pcs sync status --json |
| Create local sync baseline | pcs sync baseline |
| Replace local sync baseline intentionally | pcs sync baseline --force |
| Print normalized repository hashes | pcs sync hash repo |
| Capture TIA source snapshot | pcs sync snapshot tia plc=PLC_1 |
| Capture TIA snapshot with explicit TIA version | pcs sync snapshot tia plc=PLC_1 tia-version=V20 |
| Diff one repo/TIA source | pcs sync diff FB_AlarmRouting |
| Show raw repo/TIA diff | pcs sync diff FB_AlarmRouting raw |
| Preview accepting safe TIA changes | pcs sync accept tia FB_AlarmRouting --dry-run |
| Accept one safe TIA change into the repo | pcs sync accept tia FB_AlarmRouting |
| Preview accepting all safe TIA changes | pcs sync accept tia all --dry-run |
| Accept all safe TIA changes into the repo | pcs sync accept tia all |
Documentation¶
| Task | Command |
|---|---|
| Serve docs locally | pcs docs serve |
| Open local docs site | pcs docs open |
| Render PlantUML diagrams | pcs docs render |
| Build docs | pcs docs build |
TIA Project Helpers¶
| Task | Command |
|---|---|
| Open configured TIA project | pcs tia open |
| Archive configured TIA project | pcs tia archive |
| Preview archive path without opening TIA | pcs tia archive dry-run |
| Archive to a custom backup folder | pcs tia archive backup="%USERPROFILE%\Documents\TIA-Archives\PCS" |
| Archive with a custom name | pcs tia archive name=PCS_before_factory_acceptance_test |
Library And Release¶
| Task | Command |
|---|---|
| Show local library/release status | pcs library status |
| Inspect a release manifest or folder | pcs library inspect path=releases/PCS_1.2.0 |
| Compare a library release | pcs library compare path=releases/PCS_1.2.0 |
| Run guided library update review | pcs library update path=releases/PCS_1.2.0 |
| Prepare a release manifest | pcs release prepare version=1.2.0 |
| Prepare a release against an explicit baseline | pcs release prepare version=1.2.0 since=pcs-library-v1.1.0 |
| Validate release artifacts | pcs release validate |
| Prepare a TIA library release step | pcs release library version=1.2.0 |
| Package a release folder | pcs release package version=1.2.0 |
First command uses pcs.cmd
Use .\pcs.cmd install tools the first time because the repository root is not on the user PATH yet. Run this first setup command from a Windows Terminal opened as Administrator so it can add the user to the local Siemens TIA Openness group. After setup, restart and use normal non-elevated VS Code terminals.
First-Time Setup Commands¶
pcs install tools¶
Run the first tool setup through pcs.cmd from the repository root in a Windows Terminal opened as Administrator:
.\pcs.cmd install tools
This command is allowed to change the user environment and, when elevated, the local Openness group membership. It adds the repository root to the user PATH, sets the CurrentUser PowerShell execution policy to RemoteSigned, and checks Python, Java, Graphviz, PlantUML, and local Siemens TIA Openness group membership.
If Python, Java, or Graphviz are missing, the command can install them with winget after confirmation. If PlantUML is missing, the command can download plantuml.jar, create a plantuml.cmd wrapper below %LOCALAPPDATA%\PCS\PlantUML, and add that folder to the user PATH.
| Tool | Used for |
|---|---|
| Python | .venv, MkDocs, repository initialization |
| Java | PlantUML diagram rendering |
Graphviz dot |
PlantUML graph layout |
| PlantUML | Diagram rendering command |
Useful options:
.\pcs.cmd install tools --check-only
.\pcs.cmd install tools --yes
| Option | Meaning |
|---|---|
--check-only |
Check PATH and tools without installing or changing the user environment. |
--yes |
Install supported missing tools without asking again. |
Restart after machine changes
After install tools succeeds, follow the next steps printed by the command. It checks whether the Siemens TIA Openness group is active in the current Windows session and only asks for sign-out or restart when needed.
pcs init¶
After restarting the terminal, initialize the repository:
pcs init
This command stays inside the repository. It creates .venv if needed, installs the pinned Python packages from requirements.txt, verifies pcs.config.json, runs a MkDocs build, checks Java, Graphviz, and TIA Openness group membership, and prints the next recommended commands.
Run it again after pulling dependency changes or after editing requirements.txt.
Configuration¶
The pcs command reads project defaults from pcs.config.json:
| Field | Meaning |
|---|---|
projectPath |
TIA Portal project path |
backupPath |
TIA archive output directory |
exportsRoot |
PLC source root, normally tia\exports |
plcs |
Default PLC targets |
plant |
Build-time plant configuration such as propulsion technology and equipment counts |
author |
Environment variable settings for generated headers |
pcs config show
Example output
Project name: PCS
Project path: C:\Users\Tom Westerling\Documents\TIA-Projekte\PCS\PCS.ap20
Exports root: C:\Users\Tom Westerling\pcs\tia\exports
PLCs: PLC_1, PLC_2
Author variable: PCS_AUTHOR
Author value: Tom Westerling
Create Sources¶
Create a new PLC source scaffold:
pcs new block FB_MyNewBlock
pcs new block 00_SYSTEM/FB_MyNewBlock
pcs new block 06_ALARMS/UDT_MyNewType
Naming is enforced
Block names must start with FB_, FC_, OB_, DB_, or UDT_. This is how the CLI chooses .scl, .db, or .udt.
| Prefix | File type |
|---|---|
FB_, FC_, OB_ |
.scl |
DB_ |
.db |
UDT_ |
.udt |
Build Tools¶
Build the local TIA Openness CLI:
pcs build
Build against a specific TIA Openness version:
pcs build tia-version=V19
Info
You normally need pcs build only after changing files in tools/tia-openness, after pulling tool changes, or when switching TIA versions.
List Project Data¶
Fast and does not open TIA:
pcs list plcs configured
Reads PLCs from the TIA project through Openness:
pcs list plcs
Lists deployable files below tia/exports:
pcs list blocks
Attention
pcs list plcs may open or attach to TIA Portal. Use pcs list plcs configured when you only want the configured target names.
Open TIA Portal is supported
TIA-facing commands first try to attach to a running TIA Portal instance with the same project path. If the matching project is not already open, the tool opens it through Openness without the user interface. This applies to pcs list plcs, pcs deploy, pcs sync snapshot tia, and pcs tia archive.
Deploy¶
Deploy all sources to all configured PLCs and compile:
pcs deploy
pcs deploy plcs=PLC_1
pcs deploy plcs=PLC_1 blocks=FB_AlarmRouting,FB_AlarmDelay
pcs deploy plcs=PLC_1 folder=06_ALARMS
pcs deploy plcs=PLC_1 blocks=FB_AlarmRouting no-compile
Dry-run before a focused deploy
Use dry-run to check which PLCs and files will be used without opening TIA.
pcs deploy plcs=PLC_1 blocks=FB_AlarmRouting dry-run
pcs deploy plcs=PLC_1 folder=06_ALARMS dry-run no-compile
Deployment options
| Option | Meaning |
|---|---|
plcs=PLC_1,PLC_2 |
Override configured PLC targets |
blocks=FB_A,DB_B |
Deploy selected block files by name |
folder=06_ALARMS |
Deploy every source below a folder |
no-compile |
Import/generate without compiling |
build |
Build the Openness CLI before deployment |
dry-run |
Resolve inputs only; do not open TIA |
tia-version=V19 |
Override detected TIA Openness version |
TIA / Repo Sync¶
Create a local repository baseline after the TIA project and tia/exports are known to be aligned:
pcs sync baseline
Show current repository source changes against that baseline:
pcs sync status
pcs sync status --json
If a TIA snapshot exists, this also compares repository sources against the TIA snapshot and prints three-way decisions across Base, Repo, and TIA. The decision groups identify safe Repo -> TIA candidates, safe TIA -> Repo candidates, same changes on both sides, and conflicts.
Use --json for GUI/tool integration.
Diff one source between repository and TIA snapshot:
pcs sync diff FB_AlarmRouting
pcs sync diff 06_ALARMS/FB_AlarmRouting.scl
pcs sync diff FB_AlarmRouting raw
The default diff is normalized like pcs sync status; it ignores whitespace noise and DB/UDT comments. Use raw when formatting differences are relevant.
Accept safe TIA-only changes from the latest TIA snapshot into tia/exports:
pcs sync accept tia FB_AlarmRouting --dry-run
pcs sync accept tia FB_AlarmRouting
pcs sync accept tia all --dry-run
pcs sync accept tia all
Only files classified by pcs sync status as safe TIA -> Repo changes are accepted. Conflicts are never copied by this command.
Print normalized hashes for the current repository source files:
pcs sync hash repo
Capture the current TIA project state as generated source files into .pcs/sync/tia-snapshot/latest:
pcs sync snapshot tia plc=PLC_1
If the configured project is already open in TIA Portal, the snapshot command attaches to that running instance. This is the fastest path during normal engineering loops.
Replace the local baseline only after confirming that TIA and repository sources are aligned:
pcs sync baseline --force
The sync baseline and TIA snapshot are written below .pcs/sync and are ignored by Git.
Library And Release Management¶
pcs library status
pcs library inspect path=releases/PCS_1.2.0
pcs library compare path=releases/PCS_1.2.0
pcs library update path=releases/PCS_1.2.0
The library commands currently use release-manifest.json and provide the controlled prompt/review layer. They do not yet perform automated TIA type synchronization.
Prepare and package a developer release:
pcs release prepare version=1.2.0
pcs release validate
pcs release library version=1.2.0
pcs release package version=1.2.0
pcs release prepare detects changed PLC source files through Git and creates release-manifest.json, changelog.md, and compatibility-notes.md below releases/PCS_<version>.
By default, release preparation compares against the previous pcs-library-v* tag. Override the baseline when needed:
pcs release prepare version=1.2.0 since=pcs-library-v1.1.0
Documentation¶
pcs docs serve
pcs docs open
Opens the local MkDocs server at http://localhost:8000. Start pcs docs serve first.
pcs docs render
Renders all .puml files below docs as SVGs.
pcs docs build
The build command asks whether PlantUML diagrams should be rendered as SVGs before MkDocs runs.
python -m pip freeze | Set-Content -Encoding ASCII requirements.txt
plantuml --svg "docs\development\diagrams\multi-plc-deployment.puml"
TIA Portal¶
Open the configured TIA Portal project:
pcs tia open
The project path is resolved from projectPath in pcs.config.json.
Create a compressed TIA Portal project archive with the TIA Openness archiver:
pcs tia archive
By default, the archive is written to backupPath from pcs.config.json and named:
<projectName>_YYYY-MM-DD-HHmm.zap20
For example:
PCS_2026-05-13-2305.zap20
Preview the resolved project path, backup folder, and archive name without opening TIA:
pcs tia archive dry-run
Useful options:
pcs tia archive backup="%USERPROFILE%\Documents\TIA-Archives\PCS"
pcs tia archive name=PCS_before_factory_acceptance_test
pcs tia archive tia-version=V20
pcs tia archive build
The command saves the TIA project first and then calls the original TIA Portal archive API through Openness. The target archive must not already exist.
If the configured project is already open in TIA Portal, pcs tia archive attaches to that running instance and archives it. Otherwise it opens the configured project through Openness first.
Advanced Scripts¶
The lower-level scripts remain available for troubleshooting and automation.
Direct Openness commands
Build the Openness CLI directly:
.\tools\tia-openness\build.ps1
Deploy directly through the Openness wrapper:
.\tools\tia-openness\deploy.ps1 `
-Project "%USERPROFILE%\Documents\TIA-Projekte\PCS\PCS.ap20" `
-Plc "PLC_1"
Deploy one source file directly:
.\tools\tia-openness\deploy.ps1 `
-Project "%USERPROFILE%\Documents\TIA-Projekte\PCS\PCS.ap20" `
-Plc "PLC_2" `
-SourceFile "tia\exports\01_PLATFORM\FB_AnalogScaling.scl"