MeshCore CLI Guide

The MeshCore CLI lets you configure, monitor, and manage your devices from the terminal. Power users and infrastructure operators use it for tasks that go beyond what the companion app offers.

This guide covers the Python-based meshcore-cli tool and the built-in serial CLI available on repeater and room server firmware.

What is the MeshCore CLI?

MeshCore has two CLI interfaces. The meshcore-cli is a Python package you install on your computer that communicates with your device over Bluetooth, USB serial, or TCP. The built-in CLI runs directly on repeater and room server firmware and is accessed via a serial terminal.

Most users only need the companion app. The CLI is for people who want to automate configuration, manage remote infrastructure, flash firmware without a browser, or integrate MeshCore into larger systems.

When to Use CLI vs App vs Web Config

Companion App

Day-to-day messaging, basic device setup, joining channels

Web Config Generator

Generating initial configuration profiles for new devices

CLI

Firmware flashing, batch configuration, remote management, diagnostics, scripting

Installing meshcore-cli

Prerequisites

Python 3.8 or newer
pip (Python package manager)
USB drivers for your device (CH340 or CP2102, depending on hardware)

Install

pip install meshcore-cli

Verify the installation:

meshcore-cli --version

Platform Notes

macOS

You may need to install CH340 drivers from the manufacturer. Use brew install python if you don't have Python installed.

Windows

Drivers usually auto-install via Windows Update. If not, download CH340 drivers from the device manufacturer. Use pip from a Command Prompt or PowerShell.

Linux / Raspberry Pi

Drivers are usually built into the kernel. You may need to add your user to the dialout group for serial port access: sudo usermod -a -G dialout $USER

Connecting to Your Device

BLE (Bluetooth) Connection

The default connection method. Works with companion, repeater, and room server firmware.

meshcore-cli --ble connect

The CLI scans for nearby MeshCore devices and lets you select which one to connect to.

Serial/USB Connection

Direct wired connection. Fastest and most reliable. Required for firmware flashing.

meshcore-cli --serial /dev/ttyUSB0

Port name varies by OS: /dev/ttyUSB0 (Linux), /dev/cu.usbserial-* (macOS), COM3 (Windows).

TCP Connection

Connect to a MeshCore device over the network. Useful for remote management of infrastructure nodes that are connected to a Raspberry Pi or other Linux system.

meshcore-cli --tcp 192.168.1.100:4403

Requires a TCP bridge running on the host machine (e.g., a serial-to-TCP proxy on a Raspberry Pi connected to the device).

Command Reference

Here are the most commonly used commands, organized by category. Run meshcore-cli help for the full list.

Cheat Sheet: Most-Used Commands

Command	What It Does	Example
info	Show device info, firmware version, battery	meshcore-cli info
config get	Read current device configuration	meshcore-cli config get
config set	Change a configuration value	meshcore-cli config set name "MyNode"
nodes	List discovered nodes and signal strength	meshcore-cli nodes
flash	Flash firmware to device	meshcore-cli flash --device /dev/ttyUSB0
reboot	Restart the device	meshcore-cli reboot

Info & Diagnostics

info Device info: firmware version, hardware type, battery level, uptime

nodes List all discovered nodes with RSSI, SNR, last seen, and hop count

status Current radio state: frequency, TX power, channel, packet stats

Configuration

config get Dump all configuration values

config set <key> <value> Set a specific config value (name, tx_power, region, etc.)

config reset Reset all settings to factory defaults

Network & Messaging

send <node> <msg> Send a direct message to a specific node

broadcast <msg> Send a broadcast message to all nodes in range

listen Monitor incoming messages in real time (Ctrl+C to stop)

Admin (Repeater/Room Server)

reboot Restart the device

flash Flash new firmware to the connected device

Common Workflows

Check My Device Status

# Connect and get device info

meshcore-cli info

# See what nodes are nearby

meshcore-cli nodes

# Check radio status and packet stats

meshcore-cli status

Change My Node Name

# Set a new name

meshcore-cli config set name "NoDak-Josh"

# Reboot for the change to take effect

meshcore-cli reboot

Update Radio Settings

# Check current settings

meshcore-cli config get

# Change TX power (in dBm)

meshcore-cli config set tx_power 20

# Reboot to apply

meshcore-cli reboot

Monitor Network Health

# Watch for incoming messages and adverts

meshcore-cli listen

# List nodes with signal quality

meshcore-cli nodes

Configure a Repeater Remotely

# Connect via TCP to a repeater behind a Raspberry Pi

meshcore-cli --tcp 192.168.1.50:4403 config get

# Update its name remotely

meshcore-cli --tcp 192.168.1.50:4403 config set name "NoDak-Fargo-RPT"

# Reboot remotely

meshcore-cli --tcp 192.168.1.50:4403 reboot

Built-in Repeater/Server CLI

Repeater and Room Server firmware include a built-in command interface accessible via serial terminal (e.g., PuTTY, minicom, or screen). This is useful when you don't have meshcore-cli installed or need direct hardware access.

How to Access

# Linux/macOS

screen /dev/ttyUSB0 115200

# Or using minicom

minicom -D /dev/ttyUSB0 -b 115200

On Windows, use PuTTY with the appropriate COM port and 115200 baud rate.

The built-in CLI supports a subset of commands focused on the device's specific role. Type help in the serial terminal to see available commands for your firmware variant.

Troubleshooting

"Command not found" after installing

Your Python scripts directory may not be in your PATH. Try running python -m meshcore_cli instead, or add the pip scripts directory to your PATH. On macOS/Linux, it's usually ~/.local/bin.

"Device not responding" on serial connection

Check the baud rate (should be 115200). Verify the correct serial port — run ls /dev/tty* (Linux/Mac) or check Device Manager (Windows) to find the right port. Try unplugging and reconnecting the USB cable. Make sure no other application (like the companion app) is holding the serial port open.

"Permission denied" on serial port (Linux)

Add your user to the dialout group: sudo usermod -a -G dialout $USER then log out and back in. Alternatively, run with sudo for a quick test (not recommended long-term).

BLE connection dropping or failing

Bluetooth connections can be flaky, especially on Linux. Make sure your computer's Bluetooth adapter is working and not connected to too many devices. Try moving closer to the MeshCore device. If issues persist, use a USB serial connection instead — it's always more reliable than BLE.