pio-settings

Display the names, values and descriptions of all PlatformIO settings

$ pio settings get

$ pio settings get [setting]

$ pio settings set [setting] [value]

$ pio settings reset

pio settings [COMMAND] [OPTIONS]
pio settings list [OPTIONS]
pio settings get [OPTIONS]
pio settings set [OPTIONS]
pio settings unset [OPTIONS]

list
    Displays all current global PlatformIO settings and their values.

get
    Retrieves the value of a specific setting identified by .

set
    Sets the value of a specific setting to . If the key does not exist, it will be created.

unset
    Removes a specific setting identified by from the global configuration.

--json-output
    An optional global flag that outputs the command's result in JSON format, useful for scripting.

--caller
    An internal flag used by PlatformIO to identify the caller process, typically not used by end-users.

The pio-settings command is a command-line utility part of the PlatformIO Core ecosystem, designed for managing global configuration settings. PlatformIO is an open-source ecosystem for IoT development, providing a cross-platform build system, library manager, and integrated debugging. The pio-settings command allows users to view, retrieve, modify, and remove global configuration options that dictate PlatformIO's behavior across all projects.

These settings are typically stored in a global configuration file, often located at ~/.platformio/config.ini. Common uses include configuring proxy settings, custom package installation directories, development server options, or other system-wide preferences. By providing a programmatic interface to manage these settings, pio-settings facilitates automation and scripting of PlatformIO environment setups, ensuring consistent behavior across different development machines or CI/CD pipelines. It's a fundamental tool for customizing the PlatformIO experience beyond project-specific configurations.

Using pio-settings requires a working installation of PlatformIO Core. Modifications made with this command are global to your PlatformIO environment and can significantly alter its behavior, potentially affecting all your PlatformIO projects. Incorrectly set values might lead to unexpected errors or functionality issues. Some changes may require restarting any active PlatformIO IDE instances or the shell to take full effect.

Global PlatformIO settings managed by pio-settings are persistently stored in the config.ini file, typically located within the PlatformIO home directory, such as ~/.platformio/config.ini on Linux/macOS or %USERPROFILE%\.platformio\config.ini on Windows. Understanding this location can be useful for manual inspection or backup.

It's crucial to differentiate between global settings handled by pio-settings and project-specific settings. Project-specific configurations, such as build flags, environment variables, or library dependencies for an individual project, are defined in the platformio.ini file located in the root of each PlatformIO project.

The pio-settings command has been an integral part of PlatformIO Core since its early development. PlatformIO was launched in 2014, and as a comprehensive IoT development environment, it quickly required robust configuration management. The command evolved with PlatformIO's feature set, adapting to new configuration needs and providing a consistent CLI interface for managing the global config.ini file. Its consistent presence underlines the importance of programmatic configuration for automation and flexible development workflows within the PlatformIO ecosystem.

pio(1), platformio.ini (PlatformIO project configuration file)