plccheck

CLI wrapper for the Siemens PLC checker/LSP written in Go.

Documentation: danielv123.github.io/vscode_siemens/docs

Usage

npx plccheck check ./path/to/project

Commands

• plccheck serve (LSP server over stdio)
• plccheck check <files-or-folders...>
• plccheck emit --target <language> <file>
• plccheck compile --out <exe> <file-or-folder>
• plccheck run <file-or-folder> [-- runtime args...]
• plccheck test [--filter <text>] [--module <path>] [--events-json] [--coverage-json <file>] [--coverage-lcov <file>] <file-or-folder>
• plccheck tia <rpc|host|list|export|diff|import|repair-library-dependencies|online|offline|snapshot|compile|download|trust> ...
• plccheck version

Testing and Coverage

Run tests for a PLC root:

npx plccheck test ./my-plc-project

Request coverage artifacts in JSON and LCOV formats:

npx plccheck test ./my-plc-project --coverage-json coverage.json --coverage-lcov coverage.info

For zero-config discovery in the Coverage Gutters VS Code extension, write the LCOV tracefile as lcov.info instead:

npx plccheck test ./my-plc-project --coverage-json coverage.json --coverage-lcov lcov.info

Note: --events-json prints a stream of execution events to stdout, while --coverage-json writes a finalized coverage report to a file. Coverage artifacts include statement, function, and branch data where runtime data is available. For AI analysis, use the file artifact from --coverage-json.

Compile and Run PLC Runtime

Build a runnable PLC runtime executable:

npx plccheck compile --out plc-run.exe ./my-plc-project

Build and run it immediately, forwarding runtime flags after --:

npx plccheck run ./my-plc-project -- --opcua-port 4849 --scan-period 24h

TIA Portal Openness

On Windows x64 machines with TIA Portal Openness V21 or newer, plccheck tia can attach to a running TIA project or open an explicit .ap21/.zap21 path.

npx plccheck tia host status --json
npx plccheck tia host install
npx plccheck tia rpc --filesystem-root exported
npx plccheck tia trust --json
npx plccheck tia export software Demo.ap21 --out exported --plc PLC_1 --delete-stale
npx plccheck tia export hardware Demo.ap21 --out exported
npx plccheck tia import --project Demo.ap21 --root exported "exported/PLC_1/Program blocks/Main.scl" --create
npx plccheck tia import --project Demo.ap21 --root exported "exported/PLC_1/Program blocks/Main.scl" --overwrite-remote-changes
npx plccheck tia import --project Demo.ap21 --root exported --skip-library-instances "exported/PLC_1"
npx plccheck tia import --project Demo.ap21 --root exported "exported/PLC_1/Program blocks"
npx plccheck tia repair-library-dependencies --project Demo.ap21 --plc PLC_1 --owner CA
npx plccheck tia compile --project Demo.ap21 --plc PLC_1 --json
npx plccheck tia online --project Demo.ap21 --plc PLC_1
npx plccheck tia online --project Demo.ap21 --plc PLC_1 --online-auth-type ProjectUser --online-user engineer --online-password-env TIA_PROJECT_PASSWORD
npx plccheck tia offline --project Demo.ap21 --plc PLC_1
npx plccheck tia snapshot --project Demo.ap21 --plc PLC_1 --json
npx plccheck tia download --project Demo.ap21 --plc PLC_1 --json

export software writes PLC roots with .plc.json files, PLC system constants, and the TIA folder structure. Its default auto engine tries the fast direct reader first and falls back to Openness; --engine direct and --engine openness force one engine. export hardware separately writes hardware.aml and deterministic hardware YAML views under hardware/, and always uses Openness. import accepts one or more source files or folders, expands folders recursively, and needs --create before creating missing TIA folders or blocks. Supported direct import sources are .scl, .s7dcl, .db, .udt, .xml, .awl, .lad, and .fbd; pass the owning source file instead of .s7res resource sidecars or .meta.json metadata sidecars. By default, import skips unchanged local files, skips local files whose TIA object changed while the local source stayed unchanged, and rejects files changed both locally and in TIA since the last metadata refresh. Pass --overwrite to import when both sides changed, or pass --overwrite-remote-changes when only the TIA object changed. Import refuses to overwrite an existing project-library type instance or one of its project-library dependencies by default; pass --skip-library-instances to leave those library-owned targets unchanged and continue importing the rest, or pass --allow-library-instance-overwrite only for an intentional mutation run. repair-library-dependencies is the safe repair path for that failure class: it recreates the named library instance's project-local dependency objects from the project library. snapshot uses TIA's online DB snapshot before moving retained values to start values, skipping safety DBs and DBs without retained members. download compiles first, uses the project-configured target, reports the selected target in JSON, and falls back to software-only changes when Siemens Openness rejects a full load because of fail-safe data.

If tia list --json shows projectPath but project commands report that TIA Openness did not expose the project, close that TIA Portal instance and rerun a verification export with npx plccheck tia export software <path> --out <dir> --engine openness to surface TIA's native open error. This often means the machine is missing a TIA product or add-on required by the project.

Device actions automatically accept non-secret TLS and online-authentication modes. If the PLC requires a project/global/password user, pass --online-auth-type, --online-user where applicable, and --online-password-env <env> so the password is read from an environment variable. Without flags, the bridge also reads PLCCHECK_TIA_ONLINE_USER_TYPE or PLCCHECK_TIA_ONLINE_AUTH_TYPE, PLCCHECK_TIA_ONLINE_USER, and PLCCHECK_TIA_ONLINE_PASSWORD.

Packaged Windows x64 builds use a stable host under %ProgramFiles%\\plccheck\\tia-openness-bridge\\v1. Manage it with tia host status|install|upgrade|uninstall; normal TIA commands automatically converge stale installed files and Siemens trust to the packaged manifest. Administrator approval may be required, and installation ensures the invoking Windows user belongs to the local Siemens TIA Openness group. tia trust remains available for explicit bridge-path inspection and development setups.

tia rpc runs a persistent newline-delimited JSON-RPC host for agentic exploration. The proxy initializes the bridge automatically, so callers send application methods directly. It supports persistent sessions, bounded object handles, reflection discovery/invocation, events, and audit reads. See the repository's docs/tia-openness-rpc.md protocol reference.