How to use the command 'pio system' (with examples)

The ‘pio system’ command provides various system-level functionalities for PlatformIO. It allows users to install and uninstall shell completion, display system-wide information, and remove unused or cached data.

Use case 1: Install shell completion for the current shell

Code:

pio system completion install

Motivation: Installing shell completion for the current shell improves productivity by providing auto-complete suggestions for PlatformIO commands, options, and arguments. It reduces the amount of typing required and helps avoid errors.

Explanation:

• pio system is the main command.
• completion is the specific functionality.
• install is the action to be performed.

Example Output:

PlatformIO shell completion has been installed successfully for Bash.
Please, restart your current shell session to apply changes.

Use case 2: Uninstall shell completion for the current shell

Code:

pio system completion uninstall

Motivation: If shell completion is no longer needed or causing any issues, uninstalling it can restore the default behavior of the shell. It is particularly useful when switching between different tools or workflows.

Explanation:

• pio system is the main command.
• completion is the specific functionality.
• uninstall is the action to be performed.

Example Output:

PlatformIO shell completion has been uninstalled successfully for Bash.
Please, restart your current shell session to apply changes.

Use case 3: Display system-wide PlatformIO information

Code:

pio system info

Motivation: Displaying system-wide PlatformIO information provides an overview of the current installation, including the version, installed platforms, and configured settings. It can be helpful for troubleshooting, verifying the installation, or sharing information with others.

Explanation:

• pio system is the main command.
• info is the specific functionality.

Example Output:

PlatformIO Core 5.1.1
Python 3.9.7
System Type: linux_x86_64
PlatformIO Home: /home/user/.platformio
...
Installed Platforms:
--------------------------
atmelavr ~ Atmel AVR
atmelsam ~ Atmel SAM
espressif32 ~ Espressif 32

Use case 4: Remove unused PlatformIO data

Code:

pio system prune

Motivation: Removing unused PlatformIO data helps free up disk space by deleting unnecessary files and directories. It can be particularly useful when the installation becomes cluttered with unused or outdated data.

Explanation:

• pio system is the main command.
• prune is the specific functionality.

Example Output:

The following directories have been removed:
/home/user/.platformio/packages/...
/home/user/.platformio/frameworks/...
/home/user/.platformio/lib/...

Use case 5: Remove only cached data

Code:

pio system prune --cache

Motivation: Removing only cached data allows users to selectively clean up temporary files used by PlatformIO. This can be useful to reclaim disk space without impacting installed packages or frameworks, which may be required for current projects.

Explanation:

• pio system is the main command.
• prune is the specific functionality.
• --cache is an option to specify that only cached data should be removed.

Example Output:

The following directories have been removed:
/home/user/.platformio/packages/.cache/...

Use case 6: List unused PlatformIO data that would be removed (dry run)

Code:

pio system prune --dry-run

Motivation: Performing a dry run of the ‘pio system prune’ command allows users to see a list of unused PlatformIO data that would be removed without actually deleting it. This can help ensure that the cleanup operation does not unintentionally delete important data.

Explanation:

• pio system is the main command.
• prune is the specific functionality.
• --dry-run is an option to simulate the removal process without actually deleting any files or directories.

Example Output:

The following directories would be removed (dry run):
/home/user/.platformio/packages/...
/home/user/.platformio/frameworks/...
/home/user/.platformio/lib/...

Conclusion:

The ‘pio system’ command provides several important functionalities for managing PlatformIO installations. From installing shell completion to removing unused data, these commands enhance productivity, provide system-wide information, and help maintain a clean and efficient PlatformIO environment. Be cautious when removing data using the ‘prune’ functionality and consider performing dry runs first to review the list of files and directories that would be removed.