Skip to main content
Pitch In Subscribe

MeshCore CLI Configuration

MeshCore nodes can be configured using two distinct CLI systems:systems. theThe meshcore-cli Python tool drives a Companion node (recommendedBLE/USB-Companion forfirmware) mostover users)BLE, andTCP, theor Serial. The serial terminal/ web-console CLI (low-leveldocumented access,at worksdocs.meshcore.io/cli_commands withoutadministers Python).Repeater, BothRoom operateServer, overand USBSensor serial.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.8+.10 or newer. On Windows, ensure Python and pippip/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 portsdevices, then exit
meshcore-cli ports-l

# Connect (auto-detectsvia portserial ifand onlyrun onea device is connected)command
meshcore-cli connect

# Connect to a specific port
meshcore-cli connect --ports COM5 infos          # Windows
meshcore-cli connect --ports /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

CommandDescription
meshcore-cli info-s COM5 infosShowPrint node info (name, ID, firmwarebattery). version,Alias: batteryi
meshcore-cli contacts-s COM5 verListShow allfirmware knownversion. contactsAlias: with signal datav
meshcore-cli -s COM5 contactsList 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 set-s role repeaterSet node role (repeater, router, client) meshcore-cliCOM5 set presettx usaApply USA/Canada frequency preset meshcore-cli set txpower 2722Set 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 advert-hopsflood.advert.interval flood12SetFlood advertisementadvert hopcadence modein hours (floodrange or3–168, 0)default 12) meshcore-cli -s COM5 set advert-advert.interval 72060SetSeparate advertisementzero-hop intervaladvert cadence in minutes (720=12h)60–240) meshcore-cli -s COM5 set lat 47.6062
meshcore-cli --s COM5 set lon -122.3321Set node position (decimal degrees). Latitude and longitude are set with separate commands — there is no --lon flag meshcore-cli -s COM5 rebootReboot the node meshcore-cli factory-reset-s COM5 eraseWipeErase / 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 asthe aradio networkparameters repeater(USA/Canada: with910.525 floodMHz, advertisementsBW meshcore-cli62.5 kHz, SF 7, CR 5)
set roleradio repeater910.525,62.5,7,5

meshcore-cli# Or set presetfrequency usaon meshcore-cliits own (MHz, not kHz)
set advert-hopsfreq flood910.525

meshcore-cli# Flood advert cadence (hours)
set advert-flood.advert.interval 72012

meshcore-cli# TX power in dBm (1-22; 22 is the SX1262 chip max)
set txpowertx 2722

meshcore-cli# Node name
set name "MY-REPEATER-NAME"NAME

# Set positionPosition so the repeater appears on network maps meshcore-cli(lat/lon set separately)
set lat 47.6062
--set lon -122.3321 --alt 150

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

AllRepeater, MeshCoreRoom nodesServer, and Sensor firmware (and serial-enabled Companions) expose a raw serial commandconsole, interfacecommonly at 115200 baud.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 case-sensitiveentered in lowercase and terminatedsubmitted with Enter:

CommandDescription
helpget <param>ListRead alla availablesetting, commands
e.g. infoget roleShow, deviceget informationfreq, andget configurationtx, get radio contactsList all known contacts neighborsList directly-heard neighbour nodes stats-core / stats-radio / stats-packetsShow node statistics (RSSI/SNR are in stats-radio) set name My RepeaterSet 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,5Set role:freq 0=client,(MHz), 1=router,bandwidth 2=repeater(kHz), spreading factor, coding rate in one command set freq 910525910.525Set frequency in kHzMHz (e.g. 910525910.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 sftx 7Set spreading factor (7-12) set bw 62Set bandwidth in kHz (62=62.5 kHz, 125, 250, 500) set cr 5Set coding rate (5=4/5, 6=4/6, 7=4/7, 8=4/8) set txpower 2722Set TX power in dBm (valid range 1–22). The command is set tx, not set txpower set lat 47.6062Set latitude set lon -122.3321Set longitude advertSend a flood advertisement (advert.zerohop for zero-hop) rebootReboot device eraseErase / factory reset (destructive)

Web-based configuration interfaces

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

ToolURLPurpose
MeshCore Web Flasherflasher.meshcore.io/flasherco.ukFlash firmware via WebSerial (Chrome/Edge). Choose the firmware variant (Companion / Repeater / Room Server / Sensor) here
MeshCore Web Configconfig.meshcore.devioConfigure node settings via WebSerial (the official URL; config.meshcore.dev is not canonical)
MeshCore Web App (NZ)app.meshcore.nzCommunity-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.

  1. Flash with repeaterRepeater firmware (using the web flasher or(this PlatformIO)
is Applywhat USA/Canadasets preset:the repeater role — there is no meshcore-cli set presetrole usacommand) Set role:the radio parameters explicitly (USA/Canada): meshcore-cli set roleradio repeater910.525,62.5,7,5 Set name (use something descriptive): meshcore-cli set name "MT-RAINIER-SOUTH"SOUTH Set position:position (lat/lon separately): meshcore-cli set lat 46.8523 --then set lon -121.7603 --alt 1234 Set flood advertisements:advert cadence: meshcore-cli set advert-hopsflood.advert.interval flood12 Set TX power appropriate for antenna + FCC EIRP:limits: meshcore-cli set txpowertx 2722. 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 Verify:Verify settings: meshcore-cliget inforadio, get tx, get role Reboot: meshcore-cli reboot
Back to top