Meshtastic from the Command Line - Setup, Debug and Configuration

March 17, 2026

3 min read

Meshtastic from the Command Line - Setup, Debug and Configuration

Introduction

The Meshtastic app on your phone is convenient but sometimes you hit a wall. Settings that won’t save, connections that don’t work, or simply the desire to automate configuration. That’s exactly where the Meshtastic Python CLI comes in.

In this article, I’ll show you how to set up the CLI, how to connect to different device types, and which commands are really useful in everyday use and debugging.

Prerequisites

Python

The CLI runs on Python 3. Check if Python is installed:

python --version
# or
python3 --version

Minimum version is Python 3.9. If Python is missing, download it from python.org.

Warning: On Windows: Do not install Python from the Microsoft Store - it sometimes causes issues with packages. Download directly from python.org.

Create a virtual environment

It’s best to run the CLI in its own environment so there are no conflicts with other Python projects:

python -m venv meshtastic-env

# Activate:
# Linux/Mac:
source meshtastic-env/bin/activate
# Windows:
meshtastic-env\Scripts\activate

Install CLI

pip install meshtastic pyqrcode pypng

To verify:

meshtastic --version

Establish a connection

The CLI supports two connection methods - depending on the device type.

Option 1: USB / Serial

For devices connected directly to your PC via USB, such as a handheld node or a device being configured.

Connect the device via USB, then:

meshtastic --port COM3 --info        # Windows
meshtastic --port /dev/ttyUSB0 --info  # Linux/Mac

You can find the correct port under:

Windows: Device Manager → Ports (COM & LPT)
Linux/Mac: ls /dev/tty* before and after plugging in

Alternatively, the CLI tries to find the correct port automatically without --port:

meshtastic --info

Option 2: TCP/IP (Network)

For devices connected to the network via WiFi or Ethernet, such as a RAK WisBlock Gateway with Ethernet module.

meshtastic --host 192.168.x.x --info

You can find the device’s IP address in your router under DHCP clients.

Tip: All following examples use --host IP for TCP - simply replace it with --port COM3 if you’re using USB.

Basic commands

Get device information

The most important command of all - shows everything:

meshtastic --host [IP] --info

The output contains:

Firmware version
Hardware model
All configuration settings
Active nodes in the mesh
Channel configuration

Display nodes in the mesh

meshtastic --host [IP] --nodes

Shows a neat table of all known nodes with signal quality (SNR), last contact, and hardware model. Particularly useful for checking whether devices can see each other.

Receive messages live

meshtastic --host [IP] --listen

Shows all incoming packets in real-time - text messages, telemetry, position data, node info. Useful for checking whether the device is receiving anything at all.

Exit with Ctrl+C.

Send test message

meshtastic --host [IP] --sendtext "Hello Mesh"

Read and write configuration

Read single setting

meshtastic --host [IP] --get lora.modem_preset
meshtastic --host [IP] --get mqtt.enabled

Set single setting

meshtastic --host [IP] --set lora.modem_preset LONG_FAST
meshtastic --host [IP] --set lora.region EU_868
meshtastic --host [IP] --set lora.ignore_mqtt false

Set multiple settings at once - the reliable way

With some firmware variants (e.g. eth_gw), individual settings are not reliably saved via TCP. The safest method is export/import via YAML:

Export configuration:

meshtastic --host [IP] --export-config config.yaml

Edit YAML - e.g. adjust the MQTT section:

module_config:
  mqtt:
    address: 192.168.x.x
    enabled: true
    jsonEnabled: true
    tlsEnabled: false
    encryptionEnabled: false
    username: meshtastic
    password: YourPassword
    root: msh/EU_868

Import configuration back:

meshtastic --host [IP] --configure config.yaml

Tip: The YAML method is always more reliable than individual --set commands - especially for module settings like MQTT.

Manage channels

Display current channels

Channels are part of the --info output, but there’s also a direct way:

meshtastic --host [IP] --info

Under Channels: at the end of the output.

Generate QR code for channel import

meshtastic --host [IP] --qr

Shows the channel URL and - if pyqrcode is installed - a QR code directly in the terminal. Convenient for transferring the channel to other devices.

Reboot device

meshtastic --host [IP] --reboot

Debugging tips

Device doesn’t see other nodes

Check whether both devices have the same modem preset:
```
meshtastic --host [IP] --get lora.modem_preset
```
Both must be identical - e.g. both LONG_FAST.
Check whether both devices have the same region:
```
meshtastic --host [IP] --get lora.region
```
In Austria/Germany: EU_868.
Antenna connected? No antenna, no connection.

MQTT messages not arriving

Check whether MQTT is actually active:

meshtastic --host [IP] --get mqtt.enabled

Check whether JSON is enabled:

meshtastic --host [IP] --get mqtt.json_enabled

Check whether ignore_mqtt is disabled:
```
meshtastic --host [IP] --get lora.ignore_mqtt
```
Should be false.
Check the Mosquitto log to see whether the device is connecting and whether authentication is working.

Settings are not being saved

With eth_gw firmware via TCP: use the YAML method instead of individual --set commands - see above.

Connection fails

For TCP:

Error connecting: [WinError 10061] No connection could be made

→ Device not reachable or wrong port. Check IP in router, ping device.

For USB:

No Serial Meshtastic device detected

→ Wrong COM port or device not in normal mode (not in bootloader mode, so don’t double-reset).

Conclusion

The Meshtastic CLI is an indispensable tool once you go beyond basic setup. Especially the YAML export/import has saved me a lot of time with gateway configuration - and --listen is gold when you want to check whether anything is actually happening in the mesh.

This article is part of a series on Meshtastic and Home Assistant.