pio-run

List all available project targets

$ pio run --list-targets

$ pio run --list-targets [[-e|--environment]] [environment]

$ pio run

$ pio run [[-e|--environment]] [environment1] [[-e|--environment]] [environment2]

$ pio run [[-t|--target]] [target1] [[-t|--target]] [target2]

$ pio run [[-c|--project-conf]] [path/to/platformio.ini]

pio run [OPTIONS]

--environment, -e
    Specify one or more build environments defined in platformio.ini to run tasks against.

--target, -t
    Specify a build target. Common targets include build (default), upload, clean, program, uploadfs, and monitor.

--project-dir, -d
    Specify the path to the PlatformIO project directory. Defaults to the current working directory.

--build-dir, -b
    Specify a custom path for the build output directory where compiled objects and firmware reside.

--upload-port, -p
    Specify the serial port or network address for uploading the firmware. Overrides the upload_port setting in platformio.ini.

--clean
    Clean compiled object files and build artifacts from the project's build directory.

--silent, -s
    Suppress verbose output and progress messages during the build or upload process.

--json-output
    Output build and upload results in a machine-readable JSON format, useful for scripting and integration.

--verbose, -v
    Enable verbose output, displaying detailed information about the build process, including compiler commands and their output.

--ignore-lib-deps
    Ignore project library dependencies during the build process, preventing them from being processed or downloaded.

--force-build
    Force the rebuilding of all components, even if they appear to be up-to-date, overriding incremental build optimizations.

pio-run is a fundamental command-line interface (CLI) utility provided by PlatformIO Core, designed to manage the entire embedded development workflow for a project. It serves as the primary tool for compiling source code, linking necessary libraries, creating firmware binaries, and subsequently uploading them to target embedded devices. This command automates the complex process of cross-compilation and flashing, abstracting away the intricacies of various toolchains, SDKs, and build systems specific to different microcontrollers and development boards.

Users typically invoke pio-run from their project directory, where it reads the platformio.ini configuration file to determine the build environment, board specifications, framework, and other project-specific settings. It supports multiple build targets, allowing users to build a project, upload the compiled firmware, clean build artifacts, or even program a specific memory region. Its cross-platform nature and extensive support for a vast array of development boards and embedded frameworks make it an indispensable tool for developers working with IoT devices, microcontrollers, and embedded systems. pio-run integrates seamlessly with popular IDEs and text editors, providing a unified and efficient development experience.

pio-run requires PlatformIO Core to be installed and properly configured on the system. It also depends on a valid platformio.ini configuration file within the project directory to define build settings, board types, and other project-specific parameters. Without this configuration, the command will not know how to build or upload your project. Debugging build errors can sometimes be challenging due to the complexity of underlying toolchains and framework-specific issues.

The behavior of pio-run is heavily dictated by the platformio.ini file, which is the heart of a PlatformIO project. This file defines various build environments, specifies target boards (e.g., board = esp32dev), frameworks (e.g., framework = arduino), upload protocols, monitor settings, and project-specific build flags. Understanding and correctly configuring this file is crucial for successful project compilation and deployment.

While pio run defaults to building the project, it can be directed to perform specific actions using the --target (-t) option. Common targets include:

• build: Compiles the project (default behavior if no target is specified).
• upload: Compiles the project (if necessary) and uploads the firmware to the specified device.
• clean: Removes all generated build files and artifacts.
• program: Uploads firmware using a programmer (e.g., JTAG/SWD) instead of a serial port.
• uploadfs: Uploads a file system image (e.g., SPIFFS, LittleFS) to the device.
• monitor: Connects a serial monitor to the device after (or instead of) build/upload.

PlatformIO, and consequently its core pio-run command, was first introduced around 2014, aiming to simplify embedded development by providing a unified, cross-platform build system. From its inception, pio-run has been the central command for building and managing firmware, evolving significantly with each PlatformIO Core release. Early versions focused on basic build and upload capabilities, while later updates introduced advanced features like multiple build environments, custom targets, and improved integration with various development frameworks and debuggers. Its development has consistently prioritized automation, ease of use, and broad hardware support, making it a cornerstone of the PlatformIO ecosystem.

pio(1), pio init(1), pio board(1), pio lib(1), make(1), gcc(1)