MeshCore CLI Configuration

MeshCore nodes can be configured using two distinct CLI systems. The meshcore-cli Python tool drives a Companion node (BLE/USB-Companion firmware) over BLE, TCP, or Serial. The serial / web-console CLI documented at docs.meshcore.io/cli_commands administers Repeater, Room Server, and Sensor firmware. They are separate interfaces targeting different firmware types, not two ways of doing the same thing.

Option A: meshcore-cli (Python tool)

Installation

pipx install meshcore-cli   # recommended (upstream guidance)
pip install meshcore-cli    # also works

Requires Python 3.10 or newer. On Windows, ensure Python and pip/pipx are in PATH. meshcore-cli depends on the meshcore Python package; installing meshcore-cli pulls it in automatically.

Connect to your device

meshcore-cli has no connect or ports subcommand. You select the transport with flags, then chain the commands you want to run. The general form is meshcore-cli <connection flags> <command>.

# List available BLE / serial devices, then exit
meshcore-cli -l

# Connect via serial and run a command
meshcore-cli -s COM5 infos          # Windows
meshcore-cli -s /dev/ttyUSB0 infos  # Linux/Mac

# Connect via BLE (by name or address)
meshcore-cli -d "My Node" infos     # BLE by device name
meshcore-cli -a <ble-address> infos # BLE by address

# Connect via TCP (MeshCore default TCP port is 5000)
meshcore-cli -t 192.168.1.50 -p 5000 infos

Connection flags: -s <port> serial, -a <address> BLE address, -d <name> BLE name, -S BLE scan, -t <host> -p <port> TCP. Note: some Companion builds compile in only one interface, so a BLE-only Companion is not reachable over serial.

Common commands

Command	Description
meshcore-cli -s COM5 infos	Print node info (name, ID, battery). Alias: i
meshcore-cli -s COM5 ver	Show firmware version. Alias: v
meshcore-cli -s COM5 contacts	List known contacts (use contact_info <name> / ci for signal/path detail). Alias: lc
meshcore-cli -s COM5 set name "My Node"	Set the node's display name via meshcore-cli's set params (see set help)
Role is fixed by the flashed firmware type (Companion / Repeater / Room Server / Sensor). There is no set role; get role only reads it. To change role, reflash the desired firmware.
There is no set preset command. Apply the USA/Canada preset in the app or at config.meshcore.io, or set the radio explicitly (see the Repeater section below).
meshcore-cli -s COM5 set tx 22	Set TX power in dBm (valid range 1–22; SX1262 max is 22)
Advert behaviour is split into flood and zero-hop commands. Send a flood advert with advert; send a zero-hop advert with advert.zerohop.
meshcore-cli -s COM5 set flood.advert.interval 12	Flood advert cadence in hours (range 3–168, default 12)
meshcore-cli -s COM5 set advert.interval 60	Separate zero-hop advert cadence in minutes (60–240)
meshcore-cli -s COM5 set lat 47.6062 meshcore-cli -s COM5 set lon -122.3321	Set node position (decimal degrees). Latitude and longitude are set with separate commands — there is no --lon flag
meshcore-cli -s COM5 reboot	Reboot the node
meshcore-cli -s COM5 erase	Erase / factory reset — wipes all configuration and contacts (destructive). The command is erase, not factory-reset

Repeater-specific configuration

Repeater behaviour comes from flashing the Repeater firmware, not from a set role command. Once flashed, configure the radio and identity explicitly:

# Set the radio parameters (USA/Canada: 910.525 MHz, BW 62.5 kHz, SF 7, CR 5)
set radio 910.525,62.5,7,5

# Or set frequency on its own (MHz, not kHz)
set freq 910.525

# Flood advert cadence (hours)
set flood.advert.interval 12

# TX power in dBm (1-22; 22 is the SX1262 chip max)
set tx 22

# Node name
set name MY-REPEATER-NAME

# Position so the repeater appears on network maps (lat/lon set separately)
set lat 47.6062
set lon -122.3321

Option B: Serial / web-console CLI (Repeater, Room Server, Sensor)

Repeater, Room Server, and Sensor firmware (and serial-enabled Companions) expose a serial console, commonly at 115200 8N1. This works with any terminal emulator — no Python required. BLE-only Companion builds are not reachable over serial. Confirm the exact baud from your device's flash notes. The full command set is documented at docs.meshcore.io/cli_commands.

Connecting

• Windows: PuTTY or Windows Terminal with the COM port at 115200 8N1 (general serial-terminal guidance — verify baud per device)
• Mac/Linux: screen /dev/ttyUSB0 115200 or minicom -b 115200 -D /dev/ttyUSB0

Serial CLI commands

Type commands directly in the terminal. Commands are entered in lowercase and submitted with Enter:

Command	Description
get <param>	Read a setting, e.g. get role, get freq, get tx, get radio
contacts	List known contacts
neighbors	List directly-heard neighbour nodes
stats-core / stats-radio / stats-packets	Show node statistics (RSSI/SNR are in stats-radio)
set name My Repeater	Set node name
There is no set role command and no 0/1/2 role mapping. Role is fixed by the flashed firmware variant; get role only reads it.
set radio 910.525,62.5,7,5	Set freq (MHz), bandwidth (kHz), spreading factor, coding rate in one command
set freq 910.525	Set frequency in MHz (910.525 = 910.525 MHz). The value is MHz, not kHz
Spreading factor, bandwidth, and coding rate are fields of set radio <freq>,<bw>,<sf>,<cr> — there are no standalone set sf / set bw / set cr commands. Bandwidth is expressed as 62.5, not 62.
set tx 22	Set TX power in dBm (valid range 1–22). The command is set tx, not set txpower
set lat 47.6062	Set latitude
set lon -122.3321	Set longitude
advert	Send a flood advertisement (advert.zerohop for zero-hop)
reboot	Reboot device
erase	Erase / factory reset (destructive)

Web-based configuration interfaces

Several browser-based tools offer configuration and flashing without any local software installation:

Tool	URL	Purpose
MeshCore Web Flasher	flasher.meshcore.io	Flash firmware via WebSerial (Chrome/Edge). Choose the firmware variant (Companion / Repeater / Room Server / Sensor) here
MeshCore Web Config	config.meshcore.io	Configure node settings via WebSerial (the official URL; config.meshcore.dev is not canonical)
MeshCore Web App (NZ)	app.meshcore.nz	Community-hosted web app for messaging and config

Note: All web tools require Chrome or Edge (WebSerial API). Firefox is not supported. For web flasher use, see the Flashing Repeater Firmware page.

Recommended configuration for a new repeater deployment

1. Flash with Repeater firmware using the web flasher (this is what sets the repeater role — there is no set role command)
2. Set the radio parameters explicitly (USA/Canada): set radio 910.525,62.5,7,5
3. Set name (use something descriptive): set name MT-RAINIER-SOUTH
4. Set position (lat/lon separately): set lat 46.8523 then set lon -121.7603
5. Set flood advert cadence: set flood.advert.interval 12
6. Set TX power appropriate for antenna + FCC limits: set tx 22. Under 47 CFR 15.247(b), the max conducted power on 902–928 MHz is 30 dBm (1 W) with antennas ≤6 dBi; for every dB of antenna gain above 6 dBi you must reduce conducted power by the same amount. For bare SX1262 boards the chip max is 22 dBm
7. Verify settings: get radio, get tx, get role
8. Reboot: reboot