pio-check
run static code analysis on a PlatformIO project
TLDR
SYNOPSIS
pio check [options]
DESCRIPTION
pio check runs a static code analyzer over the sources of a PlatformIO project and reports defects grouped by severity (low, medium, high). Without `--tool` it uses the tool(s) configured in `platformio.ini`'s `check_tool` option; without `--environment` it iterates over every environment in the project.The check integrates the project's build flags, include paths, and target platform definitions so the analyzer sees the same macros and headers the compiler does — important for embedded code where `#ifdef` branches differ per MCU.
PARAMETERS
-e, --environment NAME
Run the check only for the named build environment (as defined in `platformio.ini`).-d, --project-dir PATH
Project directory. Defaults to the current directory.-c, --project-conf FILE
Alternate `platformio.ini` path.--tool NAME
Analysis tool: `cppcheck`, `clangtidy`, `pvs-studio`. May be repeated for multiple tools.--severity LEVEL
Minimum defect severity to report: `low`, `medium`, `high`.--fail-on-defect LEVEL
Return a non-zero exit code if defects of LEVEL or higher are reported.--pattern PATTERN
Glob patterns of files to analyze (alternative to `--src-filters`).--src-filters FILTER
Include/exclude filter (e.g. `+<src/app/>`, `-<src/vendor/>`). Repeatable.--flags FLAGS
Extra flags passed to the tool. Prefix with `<tool>:` to target one tool (e.g. `cppcheck: --std=c++17`).--skip-packages
Skip third-party frameworks and toolchain sources.--json-output
Emit results as JSON instead of human-readable text.-s, --silent
Suppress output except errors.-v, --verbose
Verbose output.
CONFIGURATION
`platformio.ini` options consumed by `pio check`:- `check_tool` — one or more tools (`cppcheck`, `clangtidy`, `pvs-studio`).- `check_flags` — extra per-tool flags (`cppcheck: --std=c++17`).- `check_severity` — minimum severity to report.- `checksrcfilters` — files/folders to include/exclude.- `checkskippackages` — skip framework/toolchain sources.
CAVEATS
Requires PlatformIO Core 4.0+. The chosen analyzer (e.g. `cppcheck`) must be installable via PlatformIO's package manager or already on PATH. PVS-Studio requires a license key. Analyzers only see what the preprocessor sees — code guarded by unset `#ifdef`s is skipped.
SEE ALSO
pio-run(1), pio-test(1), pio-debug(1), cppcheck(1), clang-tidy(1)
