CLI Tools for MicroPython: mpremote, ampy, and rshell

CLI tools for MicroPython are programs to manage the board from the terminal without relying on a visual IDE.

So far, we’ve seen how to interact with our board using a visual IDE like Thonny. It’s wonderful, convenient, and we recommend it for beginners. However, as we progress, the need to work from the command line often arises.

That’s where CLI (Command Line Interface) tools come in. They allow us to automate tasks, upload files in bulk, integrate workflows into CI/CD systems, or simply work with our favorite code editor (like VSCode or Sublime Text) without depending on the Thonny interface.

In this article, we’ll look at the three most important tools in the ecosystem: mpremote, ampy, and rshell.

mpremote: The Official Tool

Let’s start with the most recommendable option today. mpremote is the official tool developed by the MicroPython team. It’s modern, fast, and frankly, the one you should use in most cases.

Its great advantage is that it doesn’t require installing strange drivers and handles the serial connection very robustly.

Installation

As a proper Python tool, we install it via pip:

pip install mpremote

Basic Usage

One of the wonders of mpremote is that it automatically detects the serial port. To enter the REPL, we simply type:

mpremote

If we want to run specific commands without entering the REPL, we can chain them. For example, to see the list of files on the board:

mpremote fs ls

File Management

The commands for managing files are very similar to those in Linux (ls, cat, cp, rm, mkdir, rmdir).

# Copy a file from the PC to the board
mpremote cp main.py :main.py

# Read the contents of a file on the board
mpremote cat boot.py

# Copy entire folder contents to the board
mpremote cp -r ./my_project :

Remote Mount (mount)

This is the “killer feature” of mpremote. We can mount a folder from our computer inside the microcontroller.

This means the board “sees” the files on your PC as if they were in its internal memory. You can edit the code on your computer and run it on the board instantly, without having to copy the files each time.

mpremote mount .

This will mount the current directory (.) on the board and launch the REPL. It’s incredibly useful for rapid development.

ampy (Adafruit MicroPython Tool)

Ampy is a classic tool developed by Adafruit. For years, it was the de facto standard, especially for ESP8266 and ESP32 boards. Although it’s older than mpremote, it remains very robust and simple.

It’s ideal if you’re looking for something simple for quick upload and download scripts.

Installation

pip install adafruit-ampy

Basic Usage

Unlike mpremote, with ampy you often need to specify the port and baud rate, although you can define an AMPY_PORT environment variable to save typing it every time.

# List files
ampy --port /dev/ttyUSB0 ls

# Upload a file
ampy --port /dev/ttyUSB0 put main.py

# Read a file
ampy --port /dev/ttyUSB0 get boot.py

Execute Code Without Uploading

A very useful function of ampy is run, which allows us to execute a Python script from our PC directly on the board without saving it to the board’s flash memory.

ampy --port /dev/ttyUSB0 run test_sensor.py

rshell (Remote Shell)

If you come from the Linux world, rshell will be a treat. Developed by Dave Hylands, this tool creates a remote shell that allows us to browse the board’s files as if they were just another folder on our system.

It’s especially powerful when working with boards that don’t support native USB drive mounting (like the ESP32).

Installation

pip install rshell

Basic Usage

When you start rshell, you enter its own command line.

rshell -p /dev/ttyUSB0

Once inside, you’ll see that your board appears mounted, usually under the name /pyboard (though this can be changed). Your local file system remains accessible.

# Inside rshell
ls /pyboard        # Lists the board's files
cp main.py /pyboard # Copies main.py to the board
repl               # Enters MicroPython REPL mode

To exit REPL mode and return to rshell, press Ctrl+X.

Which Tool to Choose

So, which one do we use? Here is our recommendation based on experience:

1. mpremote: It’s the recommended option today. It’s fast, official, and the mount feature is a game-changer. If you’re starting with CLI, start here.
2. ampy: Useful for simple automation scripts (.bat or .sh) where you just want to upload a file and be done, without much interaction.
3. rshell: Great if you need to manage complex directory structures or if you’re very comfortable in a Linux terminal and want to “navigate” your microcontroller.

Visual tools are fine, but mastering the CLI gives us absolute control over our devices. And when you have to update 10 boards at once, you’ll thank yourself for learning this!