Metadata-Version: 2.4
Name: replx
Version: 2.0.0.post4
Summary: MicroPython development CLI with a separately packaged local agent.
License-Expression: MIT
Project-URL: Homepage, https://planxlab.com
Project-URL: Repository, https://github.com/PlanXLab/replx2
Project-URL: Issues, https://github.com/PlanXLab/replx2/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.5.0
Requires-Dist: typer>=0.27.3
Requires-Dist: rich>=15.0.0
Requires-Dist: mpy-cross>=1.29.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: replx-agent<3.0.0,>=2.0.0
Dynamic: license-file

# replx

[![PyPI version](https://badge.fury.io/py/replx.svg)](https://badge.fury.io/py/replx)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`replx` is a CLI tool for MicroPython development. A threaded TCP agent manages serial connections and coordinates multiple terminal sessions and boards.

It runs on Windows, macOS, and Linux and targets standard MicroPython 1.29 or newer, with firmware-matched `.mpy` compatibility support for Digi XBee3 Zigbee. Hardware commands are platform-dependent; see the detailed manual's board compatibility table. Actual board testing has been completed on Raspberry Pi Pico 2 W and Waveshare ESP32-P4-WIFI6; Digi XBee3 compatibility still requires physical board validation.

On XBee3/EFR32MG (including xnode), `pkg update`, `mip install`, and `init` compile `.py` files with the firmware-matched legacy `mpy-cross` profile and install compact `.mpy` files. Compatibility profiles cover MicroPython 1.9 through 1.23; use `--no-compile` only when source upload is intentional. `format` and the format step of `init` wait up to 120 seconds for the agent response. Both commands erase the board filesystem; back up your files first.

## What replx provides

- Shared connection management across terminal sessions
- Local agent with workspace-scoped endpoint settings
- Multiple client sessions, identified by client IP and terminal SID
- Foreground and background board handling per session
- Workspace-level default device configuration
- File operations on device storage
- Script execution, REPL access, and utility commands

## Installation

```sh
pip install replx
```

### Build and install from source (PowerShell)

From the workspace root, build and install the local wheel with:

```powershell
.\replx\build.ps1 -Install
```

Use `-Update` to upgrade dependencies before installing the local wheel, or `-NoDeps` to skip dependency installation. The script targets the active `VIRTUAL_ENV` or Conda environment, a virtual environment on `PATH`, the workspace `.venv`, and finally Python on `PATH`. If a matching local `replx-agent` wheel exists, it is installed first.

## Command summary

### Connection and session

- `setup`: Initialize workspace settings and register a default device.
- `scan`: List available serial devices.
- `status`: Show session and connection state.
- `fg`: Change the foreground device for the current session.
- `whoami`: Show the current foreground device.
- `close`: Close a device connection while leaving the agent running.
- `agent status|start|stop`: Inspect and manage the configured agent.
- `agent connect IP`: Connect this workspace to an existing agent.
- `agent disconnect IP`: Remove sessions for a client IP.
- `theme`: Show or customize UI panel colors and box style.

### Execution and interaction

- `exec` (`-c`): Execute inline Python code on the device.
- `run`: Run a local or device-side script.
- `repl`: Open an interactive REPL session.
- `shell`: Open a device file-system shell.

### File operations

- `ls`: List files and directories.
- `cat`: Print file content.
- `get`: Download files from device to local.
- `put`: Upload files from local to device.
- `cp`: Copy files or directories on device.
- `mv`: Move or rename files or directories on device.
- `rm`: Remove files or directories on device.
- `mkdir`: Create directories on device.
- `touch`: Create a file if missing; preserve existing contents.

### Device management

- `usage`: Show device storage usage.
- `reset`: Perform a soft reset.
- `format`: Format the device file system.
- `init`: Run initialization scripts on device.
- `firmware`: Check, download, or update firmware.

### Package and build

- `mip`: Search and install MicroPython packages from the official index or GitHub.
- `pkg`: Search, download, and update packages.
- `mpy`: Compile `.py` files to `.mpy`.

### Hardware

- `gpio`: Read, write, and run GPIO sequences.
- `pwm`: Generate and monitor PWM signals.
- `adc`: Read ADC pins and run a board-side scope UI.
- `uart`: Open, write, read, and monitor UART.
- `spi`: Open, write, read, and transfer SPI data.
- `i2c`: Scan, read, write, and dump I2C devices.
- `i2s`: Play I2S tones and capture or monitor an I2S microphone.
- `ws2812`: Write pixels and regions on WS2812 LED matrices.

### Connectivity

- `wifi`: Manage Wi-Fi configuration and connection state.
- `ble`: Manage BLE radio, scan, advertise, GATT server/client, and L2CAP.

## Notes

- `scan`, `status`, `whoami`, `agent`, and `agent stop` do not use the serial `--port` option.
- Most device commands can omit the port when a foreground or workspace default device is available.
- The agent defaults to `127.0.0.1:49153`. `AGENT_IP` and `AGENT_PORT` are stored in the workspace file `.vscode/.replx`.
- Non-loopback binds require the same `REPLX_AGENT_TOKEN` environment variable on the agent and client. TCP is unencrypted; use a trusted LAN or VPN.

```sh
replx agent start --port 49153
replx agent status
replx close
replx agent stop
```

For a remote agent, set `REPLX_AGENT_TOKEN` on both machines, then run `replx agent connect 192.168.1.20 --port 49153`.

## License

MIT
