pio-remote

List all active Remote Agents

$ pio remote agent list

$ pio remote agent start [[-n|--name]] [agent_name] [[-s|--share]] [example1@example.com] [[-s|--share]] [example2@example.com]

$ pio remote --agent [agent_name1] --agent [agent_name2] device list

$ pio remote --agent [agent_name] device monitor

$ pio remote --agent [agent_name] run

$ pio remote --agent [agent_name] update

$ pio remote --agent [agent_name] test

pio-remote [options]

agent
    Controls the PlatformIO Remote Agent.

agent run
    Starts the PlatformIO Remote Agent on the remote machine. Note: the agent requires the `pio account` to be logged-in on the remote side. The remote agent allows you to connect to remote PlatformIO projects and execute remote commands.

agent stop
    Stops the PlatformIO Remote Agent on the remote machine.

run
    Executes a PlatformIO command on a remote machine. Requires a configured remote environment (e.g., via SSH).

run --project-dir
    Specifies the project directory on the remote machine.

run --command
    Specifies the PlatformIO command to execute on the remote machine (e.g., `build`, `upload`).

--target
    The target build environment name.

--environment
    The project environment(s) name.

--upload-port
    Upload port PORT.

--upload-protocol
    Upload protocol PROTOCOL.

--monitor-port
    Monitor port PORT.

--monitor-speed
    Monitor speed SPEED.

version
    Shows the version of PlatformIO Remote.

The `pio-remote` command is a utility provided by the PlatformIO ecosystem that facilitates remote development workflows. It enables users to connect to and manage PlatformIO projects on remote machines (e.g., servers, virtual machines, or embedded devices). This allows developers to leverage resources, test on different architectures, or deploy directly to a target platform from their local development environment. The `pio-remote` command typically handles tasks such as: establishing SSH connections, synchronizing project files, executing build commands on the remote host, and providing access to the remote machine's filesystem and console output. It aims to streamline the process of building, testing, and deploying embedded software or IoT applications in scenarios where direct local compilation or deployment is impractical or undesirable. Note: Requires pre-installation and configuration of PlatformIO on both local and remote machines.

Requires PlatformIO to be installed on both the local and remote machines, and SSH access configured. Firewall rules may need to be adjusted to allow communication between the local and remote systems. Authentication with a valid PlatformIO account is required for remote agent functionality.

The remote environment typically requires SSH key-based authentication for secure access. You'll need to configure the `platformio.ini` file to specify the remote connection details, including the hostname, username, and path to the project directory on the remote machine.
Example:
```ini
[env:remote_build]
platform = native
extra_scripts =
pre:remote_build.py

[remote]
host = user@remote_server.com
project_dir = /path/to/remote/project
```

Common issues include SSH connection errors, incorrect project directory paths, and firewall restrictions. Verify SSH connectivity, double-check the configuration file, and ensure that the necessary ports are open on both the local and remote firewalls.

The `pio-remote` command was introduced as part of the PlatformIO ecosystem to address the growing need for remote development capabilities in embedded systems and IoT projects. Its development was driven by the need to efficiently manage projects on remote hardware and to enable collaborative development across geographically distributed teams. It has evolved to support various remote access methods, including SSH, and has integrated with PlatformIO's build and deployment workflows.

ssh(1), pio(1)