pio-check

Perform a basic analysis check on the current project

$ pio check

$ pio check [[-d|--project-dir]] [project_dir]

$ pio check [[-e|--environment]] [environment]

$ pio check --severity [low|medium|high]

$ pio check [[-v|--verbose]]

pio check [options]

--environment, -e
    Specifies one or more PlatformIO project environments to apply the check for.
If omitted, the command checks all environments defined in platformio.ini.

--json-output
    Outputs the checking results in a structured JSON format.
This option is particularly useful for programmatic processing and integration with other tools or dashboards.

--severity
    Sets the minimum severity level of issues to report.
Possible values are info, warning, and error. Issues below the specified level will not be displayed.

--filter
    Includes specific files or directories for analysis.
This option can be specified multiple times to include various paths.

--ignore
    Excludes specific files or directories from analysis.
This option can be specified multiple times to ignore various paths.

--enable-checker
    Enables specific static analysis checkers.
For example, use --enable-checker clangtidy or --enable-checker pylint.

--disable-checker
    Disables specific static analysis checkers.
Useful for temporarily turning off a checker without modifying platformio.ini.

--fail-on-defect
    Exits with a non-zero exit code if any defects (errors or warnings, depending on severity) are found.
This is crucial for CI/CD pipelines to automatically fail builds on quality issues.

--project-dir
    Specifies the path to the PlatformIO project directory.
By default, it uses the current working directory.

--keep-build-dir
    Retains the build environment files and analysis artifacts after the check process completes.

--help, -h
    Displays a help message for the pio check command and exits.

pio check is a powerful command-line utility within the PlatformIO ecosystem, designed to perform static code analysis and validate project configuration files for PlatformIO projects. It helps developers identify potential issues, coding style violations, and configuration errors early in the development cycle, promoting better code quality and maintainability.

The command integrates various industry-standard static analysis tools (linters) such as Clang-Tidy for C/C++ and Pylint for Python, among others. It analyzes source code files against configured rules, checks the consistency and correctness of the platformio.ini project configuration file, and verifies project dependencies and library installations.

Users can customize its behavior extensively via the platformio.ini file, enabling or disabling specific checkers, setting severity levels for reported issues (info, warning, error), and specifying files or directories to include or ignore. pio check is an essential tool for ensuring code robustness, especially in embedded systems development, and is often incorporated into Continuous Integration/Continuous Deployment (CI/CD) pipelines to automate quality assurance.

The pio check command requires an existing PlatformIO Core installation and a properly structured PlatformIO project. Its effectiveness heavily relies on the configured static analysis tools (e.g., Clang-Tidy, Pylint) and their presence in the system PATH or PlatformIO's toolchain. While powerful, static analysis may occasionally produce false positives or warnings that require manual review and configuration adjustments.

The behavior of pio check is highly configurable through the project's platformio.ini file.
Developers can define check_tool to specify which checkers to use (e.g., check_tool = clangtidy), set check_flags for passing arguments to the underlying tools, and define check_src_filter or check_build_flags to control the analysis scope and build settings. This allows for fine-grained control over the static analysis process tailored to specific project needs.

pio check is a cornerstone for enforcing code quality in Continuous Integration/Continuous Deployment (CI/CD) pipelines.
By incorporating pio check with the --fail-on-defect option into a CI workflow, teams can automate the detection of code quality issues. If defects of a specified severity are found, the build can be configured to fail, preventing problematic code from being merged into the main branch or deployed, thereby maintaining high code standards across the development lifecycle.

The check command is an integral part of the PlatformIO Core, an open-source ecosystem for embedded development. PlatformIO was initially launched around 2014, and the check feature was progressively introduced and enhanced to meet the growing demand for automated code quality assurance in embedded projects. It unifies various popular static analysis tools under a single, easy-to-use interface, significantly improving the development workflow for professional engineers and hobbyists alike.

pio(1), pio run(1), pio lib(1), clang-tidy(1), pylint(1)