CLI Reference

The plexus CLI lets you start agents, add sensor capabilities, scan hardware, and monitor your device from the terminal.

Install it with the base package:

pip install plexus-agent

`plexus start`

Start the Plexus agent on your device. This connects to the platform, begins streaming telemetry, and listens for commands.

plexus start

Flags

Flag	Type	Default	Description
`--key`	`string`	env / config	API key. Overrides `PLEXUS_API_KEY` and config file.
`--bus`	`int`	`1`	I2C bus number. Use `0` on older Raspberry Pi models.
`--name`	`string`	none	Display name for this device in the dashboard.

Examples

# Start with default settings (key from env)
plexus start
 
# Specify API key and device name
plexus start --key plx_xxxxx --name "test-rig-01"
 
# Use I2C bus 0 (Raspberry Pi Model A/B)
plexus start --bus 0

`plexus add`

Add sensor capabilities to your device configuration. Run without arguments to open the interactive picker.

plexus add

Or specify capabilities directly:

plexus add sensors can camera

Available Capabilities

Capability	Description
`sensors`	I2C sensors (IMU, temperature, pressure, etc.)
`can`	CAN bus (SocketCAN)
`mavlink`	MAVLink (drones, autopilots)
`mqtt`	MQTT broker
`camera`	USB/CSI camera capture
`serial`	Serial port (RS-232, UART)
`system`	System health (CPU, memory, disk, temperature)
`picamera`	Raspberry Pi CSI camera (Pi 4/5)
`tui`	Live terminal dashboard

Examples

# Interactive picker — shows checkboxes for each capability
plexus add
 
# Add I2C sensors and CAN bus
plexus add sensors can
 
# Add everything
plexus add sensors can mavlink mqtt camera serial system

`plexus run`

Run the agent with full configuration. This is the primary command for production deployments.

plexus run

Flags

Flag	Type	Default	Description
`-n, --name`	`string`	none	Device name for fleet identification.
`--live`	`bool`	`false`	Show live terminal dashboard.
`--auto-install`	`bool`	`false`	Auto-install missing Python dependencies.
`--no-sensors`	`bool`	`false`	Disable I2C sensor auto-detection.
`--no-cameras`	`bool`	`false`	Disable camera auto-detection.
`-b, --bus`	`int`	`1`	I2C bus number.
`-s, --sensor`	`string`	none	Sensor type to use (e.g. `system`). Repeatable.
`--mqtt`	`string`	none	MQTT broker to bridge (e.g. `localhost:1883`).
`--mqtt-topic`	`string`	`sensors/#`	MQTT topic to subscribe.

Examples

# Start with auto-detected hardware
plexus run
 
# Live terminal dashboard
plexus run --live
 
# Stream CPU, memory, disk, thermals
plexus run --sensor system
 
# Auto-install missing dependencies
plexus run --auto-install
 
# Bridge MQTT data
plexus run --mqtt localhost:1883
 
# Skip hardware auto-detection
plexus run --no-sensors --no-cameras

Live Terminal Dashboard

Pass --live to open a real-time terminal UI showing all active metrics, connection status, and throughput:

┌─ plexus ── rig-A ── ● connected ── 142 pts/sec ─────────────┐
│                                                               │
│  temperature    72.5 °C   ████████████████░░░░░░░░  72%      │
│  humidity       45.2 %    █████████░░░░░░░░░░░░░░░  45%      │
│  motor.rpm      3450      ████████████████████████░  95%      │
│  pressure       1013 hPa  ████████████████████░░░░  80%      │
│                                                               │
│  Buffer: 0 pending │ Session: test-042 │ Uptime: 2h 14m      │
└───────────────────────────────────────────────────────────────┘

Press q to quit, f to flush the buffer, s to start/stop a session.

`plexus pair`

Pair your device with your Plexus account. You only need to do this once per device.

plexus pair

Two Pairing Methods

Method 1: API key (headless devices)

plexus pair --key plx_xxxxx

The key is saved to ~/.plexus/config.json and used for all future connections.

Method 2: Browser pairing (devices with a display)

plexus pair

This prints a URL and a 6-digit code. Open the URL in your browser, enter the code, and the device is paired.

→ Open https://app.plexus.company/auth/device
→ Enter code: 482 913
→ Waiting for confirmation...
✓ Paired as "test-rig-01"

`plexus scan`

Detect connected hardware — I2C sensors, CAN interfaces, serial ports, and cameras.

plexus scan

Flags

Flag	Type	Default	Description
`-a, --all`	`bool`	`false`	Show all I2C addresses (including unknown).
`-b, --bus`	`int`	`1`	I2C bus number.
`--setup`	`bool`	`false`	Automatically configure detected hardware.
`--json`	`bool`	`false`	Output results as JSON.

Examples

# Scan I2C bus (default)
plexus scan
# → Found MPU6050 at 0x68
# → Found BME280 at 0x76
# → Found INA219 at 0x40
 
# Scan everything
plexus scan --all
# → I2C: MPU6050 (0x68), BME280 (0x76)
# → CAN: can0 (500 kbit/s)
# → Serial: /dev/ttyUSB0 (GPS)
# → Camera: /dev/video0 (USB 720p)
 
# Scan and auto-configure
plexus scan --setup
 
# Machine-readable output
plexus scan --json

`plexus status`

Check the connection status of the currently running agent.

plexus status

Config:     ~/.plexus/config.json
Source ID:  source-a1b2c3d4
Name:       test-rig-01
Endpoint:   https://app.plexus.company
Auth:       plx_xxx...xxx (API key)
  ✓ Connected

`plexus doctor`

Diagnose common issues with your setup — missing dependencies, connectivity problems, sensor permissions.

plexus doctor

  Configuration
  ✓ Config file: ~/.plexus/config.json
  ✓ API key: plx_xxx...xxx
  ✓ Endpoint: https://app.plexus.company
  ✓ Source ID: source-a1b2c3d4

  Network
  ✓ DNS resolves: app.plexus.company
  ✓ HTTP reachable: https://app.plexus.company
  ✓ Authentication: valid

  Dependencies
  ✓ requests: installed
  ✓ click: installed
  ✓ websockets: installed

  Hardware Permissions
  ✓ I2C bus 1: accessible
  ✗ /dev/video0: permission denied
    Fix: sudo usermod -aG video $USER

  System
  Platform:   Linux aarch64
  Python:     3.11.2
  Hostname:   test-rig-01
  Agent:      v0.5.3

  5 passed, 1 failed, 0 warnings

Next Steps

Sending Data — Use the Python API directly
Adapters — Connect to CAN bus, MQTT, MAVLink, and more

Sending Data Installation