Skip to content

Search guides, devices and posts

Back to MeshCore

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.

Checked October 2026 against MeshCore 1.18.0.

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, or integrate MeshCore into larger systems. Firmware itself is flashed with the web flasher.

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

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 -v

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

Connects to a companion node running BLE companion firmware. Pair the node with your computer first (with bluetoothctl on Linux).

meshcore-cli -S

Scans for nearby MeshCore devices and lets you pick one; later commands go to the same device. To skip the scan, use meshcore-cli -a <address or name>.

Serial/USB Connection

Direct wired connection to a node running USB companion firmware. The most reliable option.

meshcore-cli -s /dev/ttyUSB0

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

TCP Connection

Connect over your network to a companion running Wi-Fi companion firmware. MeshCore's Wi-Fi companions listen on TCP port 5000, which is the default.

meshcore-cli -t 192.168.1.100 -p 5000

Use the IP address of your Wi-Fi companion. -p is only needed if it uses a port other than 5000.

Command Reference

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

Cheat Sheet: Most-Used Commands

CommandWhat It DoesExample
infosNode info: name, radio settings, TX power, positionmeshcore-cli infos
contactsList your contactsmeshcore-cli contacts
get <param>Read a setting (get help lists them all)meshcore-cli get radio
set <param> <value>Change a settingmeshcore-cli set name "MyNode"
msg <name> <msg>Send a direct messagemeshcore-cli msg "Alex" "hello"
rebootRestart the nodemeshcore-cli reboot

Info & Diagnostics

infos Node info: name, public key, radio settings, TX power and position
ver Firmware version
get stats Node status, with battery, uptime and packet counts
contacts Your contact list

Configuration

get <param> Read a setting, such as name, radio, tx, lat or lon
set <param> <value> Change a setting
get help List every setting you can read or change
clock sync Set the node's clock from your computer

Network & Messaging

msg <name> <msg> Send a direct message to a contact; add wait_ack to wait for the delivery confirmation
public <msg> Send a message on the Public channel
chan <nb> <msg> Send a message on another channel, by its number
msgs_subscribe Show messages as they arrive
advert Send an advert so other nodes can find you

Repeaters & Room Servers (over the mesh)

login <name> <pwd> Log in to a repeater or room server through your companion
cmd <name> <cmd> Send a command to a repeater you are logged in to
req_status <name> Ask a node for its status

Common Workflows

These run once and exit. Run meshcore-cli with no commands to open chat mode instead, where you can type the same commands at a prompt.

Check My Device Status

# Node info: name, radio settings, TX power

meshcore-cli infos

# Who your node knows about

meshcore-cli contacts

# Battery, uptime and packet counts

meshcore-cli get stats

Change My Node Name

# Set a new name

meshcore-cli set name "NoDak-Josh"

# Send an advert so other nodes see it

meshcore-cli advert

Update Radio Settings

# Check the current radio settings

meshcore-cli get radio

# Change TX power (in dBm)

meshcore-cli set tx 20

# Confirm the new value

meshcore-cli get tx

Watch the Mesh

# Show messages as they arrive (Ctrl+C to stop)

meshcore-cli msgs_subscribe

# List your contacts

meshcore-cli contacts

Configure a Repeater Remotely

# Log in to the repeater over the mesh, through your companion

meshcore-cli login "NoDak-Fargo-RPT" "admin-password"

# Log in and send it a command in one go

meshcore-cli login "NoDak-Fargo-RPT" "admin-password" cmd "NoDak-Fargo-RPT" "set name NoDak-Fargo-RPT"

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.

Companion firmware got its own built-in CLI in v1.18, reachable from the MeshCore app's settings and, with permission, over the mesh. See our MeshCore companion CLI guide for every command and how Remote CLI works.

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.

Related Guides

Using Meshtastic instead? See our Meshtastic CLI guide for the Python-based Meshtastic CLI with commands for configuration, messaging, and firmware flashing.