# 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](https://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

<table id="bkmrk-commanddescription-m"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td>`meshcore-cli -s COM5 infos`</td><td>Print node info (name, ID, battery). Alias: `i`</td></tr><tr><td>`meshcore-cli -s COM5 ver`</td><td>Show firmware version. Alias: `v`</td></tr><tr><td>`meshcore-cli -s COM5 contacts`</td><td>List known contacts (use `contact_info <name>` / `ci` for signal/path detail). Alias: `lc`</td></tr><tr><td>`meshcore-cli -s COM5 set name "My Node"`</td><td>Set the node's display name via meshcore-cli's `set` params (see `set help`)</td></tr><tr><td colspan="2">*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.*</td></tr><tr><td colspan="2">*There is no `set preset` command. Apply the USA/Canada preset in the app or at [config.meshcore.io](https://config.meshcore.io), or set the radio explicitly (see the Repeater section below).*</td></tr><tr><td>`meshcore-cli -s COM5 set tx 22`</td><td>Set TX power in dBm (valid range 1–22; SX1262 max is 22)</td></tr><tr><td colspan="2">*Advert behaviour is split into flood and zero-hop commands. Send a flood advert with `advert`; send a zero-hop advert with `advert.zerohop`.*</td></tr><tr><td>`meshcore-cli -s COM5 set flood.advert.interval 12`</td><td>Flood advert cadence in **hours** (range 3–168, default 12)</td></tr><tr><td>`meshcore-cli -s COM5 set advert.interval 60`</td><td>Separate zero-hop advert cadence in **minutes** (60–240)</td></tr><tr><td>`meshcore-cli -s COM5 set lat 47.6062`  
`meshcore-cli -s COM5 set lon -122.3321`</td><td>Set node position (decimal degrees). Latitude and longitude are set with separate commands — there is no `--lon` flag</td></tr><tr><td>`meshcore-cli -s COM5 reboot`</td><td>Reboot the node</td></tr><tr><td>`meshcore-cli -s COM5 erase`</td><td>Erase / factory reset — wipes all configuration and contacts (destructive). The command is `erase`, not `factory-reset`</td></tr></tbody></table>

### 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](https://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:

<table id="bkmrk-commanddescription-h"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td>`get <param>`</td><td>Read a setting, e.g. `get role`, `get freq`, `get tx`, `get radio`</td></tr><tr><td>`contacts`</td><td>List known contacts</td></tr><tr><td>`neighbors`</td><td>List directly-heard neighbour nodes</td></tr><tr><td>`stats-core` / `stats-radio` / `stats-packets`</td><td>Show node statistics (RSSI/SNR are in `stats-radio`)</td></tr><tr><td>`set name My Repeater`</td><td>Set node name</td></tr><tr><td colspan="2">*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.*</td></tr><tr><td>`set radio 910.525,62.5,7,5`</td><td>Set freq (MHz), bandwidth (kHz), spreading factor, coding rate in one command</td></tr><tr><td>`set freq 910.525`</td><td>Set frequency in **MHz** (910.525 = 910.525 MHz). The value is MHz, not kHz</td></tr><tr><td colspan="2">*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`.*</td></tr><tr><td>`set tx 22`</td><td>Set TX power in dBm (valid range 1–22). The command is `set tx`, not `set txpower`</td></tr><tr><td>`set lat 47.6062`</td><td>Set latitude</td></tr><tr><td>`set lon -122.3321`</td><td>Set longitude</td></tr><tr><td>`advert`</td><td>Send a flood advertisement (`advert.zerohop` for zero-hop)</td></tr><tr><td>`reboot`</td><td>Reboot device</td></tr><tr><td>`erase`</td><td>Erase / factory reset (destructive)</td></tr></tbody></table>

## Web-based configuration interfaces

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

<table id="bkmrk-toolurlpurpose-meshc"><thead><tr><th>Tool</th><th>URL</th><th>Purpose</th></tr></thead><tbody><tr><td>**MeshCore Web Flasher**</td><td>[flasher.meshcore.io](https://flasher.meshcore.io)</td><td>Flash firmware via WebSerial (Chrome/Edge). Choose the firmware variant (Companion / Repeater / Room Server / Sensor) here</td></tr><tr><td>**MeshCore Web Config**</td><td>[config.meshcore.io](https://config.meshcore.io)</td><td>Configure node settings via WebSerial (the official URL; `config.meshcore.dev` is not canonical)</td></tr><tr><td>**MeshCore Web App (NZ)**</td><td>[app.meshcore.nz](https://app.meshcore.nz)</td><td>Community-hosted web app for messaging and config</td></tr></tbody></table>

**Note:** All web tools require Chrome or Edge (WebSerial API). Firefox is not supported. For web flasher use, see the *[Flashing Repeater Firmware](https://wiki.meshamerica.com/books/meshcore-repeaters/page/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`