Using the `pio remote` Command (with examples)

List all active Remote Agents

pio remote agent list

Motivation: This command allows you to see a list of all active Remote Agents connected to your platform.

Arguments:

• None

Example Output:

Available Remote Agents:
- agent1@example.com
- agent2@example.com
- agent3@example.com

Start a new Remote Agent with a specific name and share it with friends

pio remote agent start --name agent_name --share example1@example.com --share example2@example.com

Motivation: This command allows you to start a new Remote Agent with a custom name and share it with specific email addresses. This is useful when you want to collaborate with others on a development project.

Arguments:

• --name: Specifies the name of the Remote Agent.
• --share: Specifies the email addresses of the individuals you want to share the Remote Agent with.

Example Output:

Remote Agent "agent_name" started and shared with:
- example1@example.com
- example2@example.com

List devices from specified Agents

pio remote --agent agent_name1 --agent agent_name2 device list

Motivation: This command allows you to list the devices connected to specific Remote Agents. This is useful when you want to remotely access and manage multiple devices.

Arguments:

• --agent: Specifies the name of the Remote Agent(s) whose devices you want to list.

Example Output:

Devices from "agent_name1":
- Device 1
- Device 2

Devices from "agent_name2":
- Device 3
- Device 4

Connect to the serial port of a remote device

pio remote --agent agent_name device monitor

Motivation: This command allows you to establish a serial connection to a remote device. This is useful when you want to monitor the device’s output or interact with it remotely.

Arguments:

• --agent: Specifies the name of the Remote Agent that has the device.
• device monitor: The command to establish a serial connection to the device.

Example Output:

Connected to the serial port of "device" on "agent_name".

Run all targets on a specified Agent

pio remote --agent agent_name run

Motivation: This command allows you to remotely execute all targets (e.g., build, upload) on a specific Remote Agent. This is useful when you want to offload the build process to a more powerful machine.

Arguments:

• --agent: Specifies the name of the Remote Agent on which to run the targets.
• run: The command to run all targets.

Example Output:

Running all targets on "agent_name"...
Build succeeded.
Uploading firmware...

Update installed core packages, development platforms, and global libraries on a specific Agent

pio remote --agent agent_name update

Motivation: This command allows you to update the core packages, development platforms, and global libraries installed on a specific Remote Agent. This ensures that the Agent has the latest features and bug fixes.

Arguments:

• --agent: Specifies the name of the Remote Agent on which to perform the update.
• update: The command to update the packages.

Example Output:

Updating packages on "agent_name"...
Packages updated successfully.

Run all tests in all environments on a specific Agent

pio remote --agent agent_name test

Motivation: This command allows you to remotely run all tests in all environments on a specific Remote Agent. This is useful when you want to automate the testing process and ensure compatibility across different environments.

Arguments:

• --agent: Specifies the name of the Remote Agent on which to run the tests.
• test: The command to run all tests.

Example Output:

Running tests on "agent_name"...
Test 1 passed.
Test 2 passed.