Command-Line Interface

MeshCore CLI Configuration

Manage your MeshCore nodes via the official MeshCore-cli tool. Precise control for advanced users and automation.

What Is The MeshCore CLI?

The MeshCore command-line interface (MeshCore-cli) is a Python-based tool enabling terminal communication with your MeshCore companion radio. The CLI supports connections via Bluetooth Low Energy (BLE), TCP/IP, or serial.

Additionally, repeaters and room servers possess their own built-in CLI accessible via USB serial or remotely. This permits direct device configuration of frequency, transmission power, name, and other settings.

This guide covers both approaches: the MeshCore-cli Python tool for companion radios, and the serial CLI for repeaters and room servers. Essential reading for system administrators, power users, and anyone interested in scripting or automation.

Why Use The CLI?

⚡

Speed And Efficiency

Configure nodes in seconds with a few commands, far quicker than navigating graphical interfaces.

🤖

Scriptable Automation

Write bash or Python scripts to execute batch operations across multiple nodes simultaneously.

🔧

Complete Control

Access all settings including advanced radio parameters and repeater configuration.

📡

Multiple Connections

Connect via Bluetooth, WiFi/TCP, or serial. Choose whichever suits your setup.

🖥️

Remote Management

Manage repeaters remotely via the remote admin feature from CLI or mobile app.

💬

Interactive Chat Mode

The CLI includes an interactive mode with tab-completion, command history, and real-time messaging.

Installing MeshCore CLI

The MeshCore-cli tool is installed as a Python package via pip or pipx. It operates on Windows, macOS, Linux, and Raspberry Pi. Requires Python 3.10 or newer.

Step 1: Verify Python Version

Python 3.10 or newer is required. Check your version:

python3 --version

If Python is absent, download it from python.org

Step 2: Install MeshCore-cli

Install the official MeshCore CLI tool via pipx (recommended) or pip:

# Via pipx (recommended)

pipx install meshcore-cli

# Or via pip

pip3 install meshcore-cli

Step 3: Verify Installation

Confirm successful installation by opening the help:

meshcli -h

Basic CLI Commands

The MeshCore-cli supports both command-line parameters and an interactive chat mode. Launch without arguments for interactive mode.

Select Device (BLE)

Scan and select your MeshCore device via Bluetooth. The CLI remembers your selection for subsequent sessions.

meshcli -S

Connect Via TCP/IP

Connect to a MeshCore node via WiFi/network if TCP server is active.

meshcli -t 192.168.1.100

Connect Via Serial

Connect via USB serial port for direct communication with your node.

meshcli -s /dev/ttyUSB0

Send Message

Send a text message to a specific contact or broadcast to everyone.

meshcli send "Hello MeshCore network!"

View Contacts

View all known nodes in your network with their status and signal strength.

meshcli contacts

Interactive Mode

Launch without commands for interactive chat mode with tab-completion and history.

meshcli

Repeater And Room Server CLI

Repeaters and room servers have a built-in CLI accessible via USB serial (terminal/PuTTY) or via the T-Deck CLI. Following flashing, basic settings are configured here.

Set Frequency / Preset (Required)

Following flashing, set the correct regional preset for your deployment. In the United States/Canada, use 915 MHz hardware with the USA/Canada (Recommended) preset. In the EU, use 868 MHz hardware with the EU868 preset. The preset auto-configures frequency, bandwidth, spreading factor, and coding rate.

set freq 869.4

reboot

Name And Location

Assign your repeater a recognizable name and optionally GPS coordinates for map display.

set name MijnRepeater

set lat 52.3676

set lon 4.9041

Configure Transmission Power

Adjust transmission power in dBm. Start with moderate values and increase only if you have real coverage gaps. Always stay within what your hardware supports and what is permitted where you operate.

set tx 22

Repeater Settings

Configure repeater-specific options such as hop limits and advertisement intervals.

set flood.max 3

set advert.interval 30

set flood.advert.interval 3

Web-Based Configuration

Beyond the CLI, repeaters and room servers can also be configured via web-based tools. This is often simpler for beginners.

MeshCore webflasher

Flash firmware and configure directly via browser at meshcore.io/flasher. Click "Console" after flashing for CLI access.

meshcore.io/flasher →

MeshCore Config Tool

Configure existing repeaters via config.MeshCore.dev - connect via USB and adjust settings in the browser.

config.meshcore.dev →

Minimal Configuration After Flashing

Following MeshCore firmware flashing, these steps are minimally required:

# 1. Set regional preset / frequency
 # If your device supports presets:
 set preset {us|eu}
 # Or set an explicit frequency in MHz if required by your firmware:
 set freq {MHz}

# 2. Reboot to apply changes
reboot

# 3. Optional: assign your repeater a name
set name Colorado-Repeater

# 4. Optional: set location for map display
set lat 39.7392
set lon -104.9903

Frequently Asked Questions About CLI

What distinguishes MeshCore-cli from the serial CLI?

The MeshCore-cli (meshcli) is a Python tool communicating with your companion radio via BLE, TCP, or serial. The serial CLI is built into repeaters and room servers, accessed directly via USB/terminal. Each has distinct commands and use cases.

How do I connect via Bluetooth?

On Linux, first pair your device via bluetoothctl. Then use meshcli -S to select your device. The CLI remembers your choice in ~/.config/MeshCore.

Can I configure repeaters remotely?

Yes! Via the Remote Admin feature you can manage repeaters and room servers over LoRa. This works from MeshCore-cli with repeater commands, or via the mobile app with Remote Management.

Which frequency should I use in America?

Use the USA/Canada (Recommended) preset with 915 MHz hardware. This applies the correct North America channel plan (902-928 MHz). Avoid mixing EU868 and US/Canada settings in the same network - nodes must match to communicate.

How do I reset my repeater to factory settings?

Via the serial CLI you can use erase to wipe the file system. This removes all settings. You will need to configure frequency again afterwards.

Where can I find all available commands?

For MeshCore-cli: meshcli -h displays all options. For the repeater/room server CLI: help in the serial console. The complete reference is available on the MeshCore GitHub wiki.

Master The Command-Line

With the MeshCore CLI you gain professional control over your mesh network. Ideal for repeater management, scripting, and advanced configuration.

Learn Python API Join Discord Community