# MeshCore CLI Reference

# Connecting to Your Device

The MeshCore CLI (`meshcore-cli`) supports three connection methods. Choose the one that matches your hardware and situation.

## Serial (USB)

The most reliable method. Connect your device via USB and specify the serial port with `-s`:

```
meshcore-cli -s /dev/ttyUSB0
```

The serial port must be given explicitly with `-s` — it is not auto-detected. Use the port that matches your system:

```
meshcore-cli -s /dev/ttyUSB0   # Linux/macOS
meshcore-cli -s COM3           # Windows
```

If you need to set a non-default baud rate, pass it with `-b` (for example `-b 115200`). MeshCore serial consoles commonly run at **115200**, matching the firmware's default, but set it explicitly with `-b` if your connection fails.

## Bluetooth (BLE)

Connect wirelessly to a nearby device. BLE is the default transport — scan for devices and pick one with `-S`, or target a known device directly with `-a <address>` or `-d <name>`:

```
meshcore-cli -S                # scan and select a BLE device
meshcore-cli -a <ble-address>   # connect to a known device
```

If the device does not appear, ensure it is powered on and not already connected to the MeshCore app. A BLE companion connection is a single GATT link, so generally only one client can connect at a time.

## TCP (Wi-Fi / LAN)

Connect to a device that exposes a TCP interface (useful for remote administration of fixed nodes). Use `-t` for the host and `-p` for the port:

```
meshcore-cli -t 192.168.1.100 -p 5000
```

Replace the IP with the device's actual address. Port **5000** is the meshcore-cli TCP default.

## Verifying Connection

Once connected, run `infos` (shortcut `i`) to confirm the connection and see device details:

```
infos
```

The `infos` output includes the node's public key, node name, TX power, location (lat/lon), and radio configuration (frequency, bandwidth, spreading factor, coding rate). Firmware version is shown by the separate `ver` command, and battery/telemetry by `self_telemetry` (shortcut `t`).

# Full Command Reference

MeshCore has two command surfaces. The device-side **serial CLI** (canonical reference: `docs.meshcore.io/cli_commands`) uses bare `get`/`set` verbs and is used to configure repeaters and room servers over USB serial. The host tool **meshcore-cli** (invoked as `meshcore-cli`/`meshcli`) connects to a companion radio over BLE, TCP, or Serial; commands can be passed on the command line or entered in interactive chat mode. The tables below note which surface each command belongs to.

## Device Information &amp; Status

<table id="bkmrk-commandpurpose-infod"> <thead><tr><th>Command</th><th>Purpose</th></tr></thead> <tbody> <tr><td>`infos` (alias `i`)</td><td>meshcore-cli: print node info (public key, TX power, radio params, name, location). For firmware version use `ver`; for battery/telemetry use `self_telemetry` / `req_status`.</td></tr> <tr><td>`stats-radio` / `stats-core` / `stats-packets`</td><td>Serial CLI: radio stats (noise floor, RSSI/SNR, airtime), core stats (battery, uptime, queue), and packet counters. There is no bare `status` command.</td></tr> <tr><td>`contacts` / `list` (alias `lc`)</td><td>meshcore-cli: list known contacts (nodes you have received adverts from). Use `node_discover <filter>` (`nd`) to discover nodes by type, or `neighbors` on a repeater's serial CLI.</td></tr> <tr><td>`get <param>`</td><td>Read a setting (e.g. `get radio`, `get name`, `get tx`). Run `get help` for the parameter list. There is no `config get` command.</td></tr> </tbody></table>

## Configuration

<table id="bkmrk-commandpurpose-confi"> <thead><tr><th>Command</th><th>Purpose</th></tr></thead> <tbody> <tr><td>`set name <name>`</td><td>Set the node name (no `config set` prefix).</td></tr> <tr><td>`set tx <dbm>`</td><td>Set LoRa transmit power in dBm (valid 1–22 for SX1262). Choose a value that keeps EIRP within your region's limit — 36 dBm EIRP in the US per FCC Part 15.247. Setting too high may violate local law.</td></tr> <tr><td>`erase`</td><td>Restore factory defaults. **Serial-only and destructive.** There is no `config reset` command.</td></tr> <tr><td>`set lat <degrees>`</td><td>Set latitude in degrees.</td></tr> <tr><td>`set lon <degrees>`</td><td>Set longitude in degrees.</td></tr> <tr><td>`password <new_password>`</td><td>Set the admin password. Any node presenting this password is added to the admin ACL.</td></tr> </tbody></table>

## Messaging

<table id="bkmrk-commandpurpose-send-"> <thead><tr><th>Command</th><th>Purpose</th></tr></thead> <tbody> <tr><td>`msg <name> <message>` (alias `m`)</td><td>meshcore-cli: send a direct message to a contact by name.</td></tr> <tr><td>`public <message>` or `chan <nb> <message>`</td><td>meshcore-cli: send to the public channel (0) or to channel number &lt;nb&gt;. Channel messages flood to subscribers. There is no `broadcast` command.</td></tr> <tr><td>`msgs_subscribe` (alias `ms`)</td><td>meshcore-cli: display messages as they arrive. Use `recv` (`r`) / `wait_msg` (`wm`) to read them, or chat mode. There is no `listen` command.</td></tr> </tbody></table>

## Network &amp; Routing

<table id="bkmrk-commandpurpose-adver"> <thead><tr><th>Command</th><th>Purpose</th></tr></thead> <tbody> <tr><td>`advert`</td><td>Trigger immediate advertisement broadcast (flood). Use `advert.zerohop` for a zero-hop advert.</td></tr> <tr><td>`set flood.advert.interval <hours>`</td><td>Flood advert interval in hours (valid 3–168; default 12).</td></tr> <tr><td>`set path.hash.mode <0|1|2>`</td><td>Advert path hash size (0=1-byte, 1=2-byte, 2=3-byte; **default 0**). Affects only this node's own adverts, not forwarding or routing-table behaviour; requires firmware ≥ 1.14.</td></tr> <tr><td>`region put <name> [parent]`</td><td>Create a region. Names are user-defined (e.g. `region put #USA`) — there are no predefined US/state scopes. Flooding must be enabled separately.</td></tr> <tr><td>`region put <child> <parent>`</td><td>Create a nested region under a parent (e.g. `region put #Colorado #USA`). Names are user-defined, not ISO/region codes.</td></tr> <tr><td>`region save`</td><td>Save region configuration.</td></tr> </tbody></table>

## Repeater &amp; Room Server

<table id="bkmrk-commandpurpose-set-a"> <thead><tr><th>Command</th><th>Purpose</th></tr></thead> <tbody> <tr><td>`set agc.reset.interval <seconds>`</td><td>AGC reset interval in **seconds** (rounded down to a multiple of 4; 0 disables). Helps with receiver desensitization.</td></tr> <tr><td>`set repeat <on|off>`</td><td>Enable/disable packet repeating on a repeater or room server (default on).</td></tr> </tbody></table>

## Firmware &amp; Maintenance

<table id="bkmrk-commandpurpose-reboo"> <thead><tr><th>Command</th><th>Purpose</th></tr></thead> <tbody> <tr><td>`reboot`</td><td>Restart the device.</td></tr> <tr><td>`start ota`</td><td>Initiate an over-the-air firmware update (nRF52). Otherwise flash via the MeshCore web flasher or esptool/UF2. There is no `flash` command.</td></tr> </tbody></table>

# Key Repeater Settings

These settings are most critical for deploying and maintaining MeshCore repeater and room server nodes.

## AGC Reset Interval - Fix Receiver Deafness

```
set agc.reset.interval 8
```

**Problem it solves:** If a high-power transmitter (such as a nearby ham radio or commercial repeater) is within range, the LoRa receiver's automatic gain control (AGC) can be driven into a saturated state. After the nearby transmission ends, the AGC does not always recover correctly, leaving the MeshCore repeater effectively deaf to normal LoRa signals.

**Symptom:** The repeater was working, a nearby radio transmission occurred, and now the repeater is not hearing any nodes even though they are transmitting normally.

**Fix:** The value is in **seconds** (rounded to a multiple of 4; `<span class="editor-theme-code">0</span>` disables the periodic reset). Setting `<span class="editor-theme-code">agc.reset.interval 8</span>` forces the AGC to reset every 8 seconds, preventing permanent desensitization.

## Flood Advertisement Interval

```
set flood.advert.interval 47
```

Controls how often the repeater floods its advert (presence). The value is in **hours** (valid 3-168, default 12). Lower values mean neighbors discover the repeater faster after power-on, but generate more radio traffic. 47 hours is a reasonable setting for a fixed infrastructure node on a busy mesh. Small meshes can advert more frequently.

## Path Hash Mode

```
set path.hash.mode 2
```

Sets the size of this repeater's own advert path-hash (it does not control message-cache granularity or forwarding):

- `<span class="editor-theme-code">0</span>` - 1-byte hash: **default**; minimal overhead, higher chance of hash collision in large networks
- `<span class="editor-theme-code">1</span>` - 2-byte hash: more precision at slightly higher overhead
- `<span class="editor-theme-code">2</span>` - 3-byte hash: highest precision; use in very large networks where collisions are observed. **Recommended**.

## Packet Repeat (Room Server)

```
set repeat on
```

On room server firmware, this enables the node to also act as a packet repeater in addition to its store-and-forward function. Only enable if the room server has good placement; a poorly-placed room server acting as a repeater can cause more harm than good to routing.

## TX Power

```
set tx 20
```

TX power is set with `<span class="editor-theme-code">set tx <dbm></span>`, valid range **1-22 dBm** (the SX1262 maximum is 22). For unlicensed operation in the US 902-928 MHz band, the 30 dBm (1 W) conducted limit is set by **FCC Part 15.247**, not Part 97. (Part 97 - licensed amateur - allows up to 10 W PEP for spread spectrum under 47 CFR 97.313(j), but it requires a license, prohibits encryption, and requires station ID, so default-encrypted MeshCore cannot lawfully run under Part 97.) Antennas over 6 dBi require a dB-for-dB reduction in conducted power. More power is not always better - an overdriven signal can desensitize nearby receivers including your own.

## Region Configuration

```
region put us
region put us-co us
region save
```

Region scopes control which nodes can see and communicate through this repeater. The hierarchical scheme (`<span class="editor-theme-code">us</span>` › `<span class="editor-theme-code">us-co</span>`) allows regional segmentation in large deployments.

## Name and Location

```
set name MyRepeater-Site1
set lat 39.7392
set lon -104.9903
```

Always set a meaningful name and accurate coordinates for infrastructure nodes. This allows map tools (such as the MeshCore map at meshcore.co.uk/map.html) to display the repeater correctly and helps operators diagnose coverage gaps.