Meshtastic CLI Guide

The Meshtastic Python CLI does everything the app does and more — batch configuration, config backup/restore, firmware flashing, and scripting. Install with pip, connect over serial or Bluetooth, and you're running.

When to Use the CLI

Most users only need the Meshtastic app (Android/iOS). The CLI is for people who want to automate configuration, manage remote nodes, flash firmware without a browser, back up and restore configs, or integrate Meshtastic into larger systems.

The CLI communicates with your device over USB serial (most common), Bluetooth, or TCP. Every setting available in the app is also available via CLI — plus some extras.

CLI vs App vs Web Client

Mobile App

Day-to-day messaging, basic device setup, map view, channel management

Web Client

Browser-based interface at client.meshtastic.org — messaging and basic config

Python CLI

Firmware flashing, config export/import, batch operations, remote management, scripting

Installation

Prerequisites

Python 3.9 or newer
pip (Python package manager)
USB serial drivers for your device (CH340 or CP2102)

Install

pip install meshtastic

Verify the installation:

meshtastic --version

Platform Notes

macOS

Install CH340 drivers from the manufacturer. Use brew install python if needed. If meshtastic isn't found after install, add ~/.local/bin to your PATH.

Windows

Drivers usually auto-install. Run from Command Prompt or PowerShell. If meshtastic isn't found, try python -m meshtastic.

Linux / Raspberry Pi

Drivers are usually built into the kernel. Add your user to the dialout group: sudo usermod -a -G dialout $USER then log out and back in.

Connecting to Your Device

USB Serial (Default)

The CLI auto-detects USB-connected devices. Just plug in and run a command.

meshtastic --info

If multiple devices are connected, specify the port: meshtastic --port /dev/ttyUSB0 --info

Bluetooth

Connect wirelessly via Bluetooth Low Energy.

meshtastic --ble --info

Scans for nearby Meshtastic devices. Specify a device name to connect directly: meshtastic --ble "MyNode" --info

TCP/IP (Network)

Connect to a device over the network. Useful for ESP32 devices with Wi-Fi enabled.

meshtastic --host 192.168.1.100 --info

Command Reference

Here are the most commonly used commands. Run meshtastic --help for the full list.

Cheat Sheet

Command	What It Does
meshtastic --info	Device info, firmware version, config summary
meshtastic --nodes	List discovered nodes with SNR, last seen
meshtastic --set <key> <val>	Change a config value
meshtastic --get <key>	Read a config value
meshtastic --sendtext "msg"	Send a broadcast text message
meshtastic --export-config	Dump full device config as YAML
meshtastic --configure <file>	Apply config from a YAML file
meshtastic --flash	Flash latest firmware to device
meshtastic --factory-reset	Reset all settings to factory defaults

Info & Diagnostics

--info Device info: firmware, hardware, battery, region, channels

--nodes List all discovered nodes with SNR, distance, and last seen time

--qr Generate a QR code for sharing your channel configuration

Configuration

--set <key> <val> Set a config value (e.g., --set device.role ROUTER)

--get <key> Read a specific config value

--export-config Export full device configuration as YAML

--configure <file> Apply configuration from a YAML file

--factory-reset Reset everything to factory defaults

Channel Management

--ch-index <N> --ch-set <key> <val> Configure a channel (name, PSK, uplink, downlink)

--ch-add <name> Add a new secondary channel

--ch-del Delete a channel (use with --ch-index)

See the channels guide for detailed channel and MQTT configuration.

Messaging

--sendtext "message" Broadcast a message to the default channel

--dest !nodeId --sendtext "msg" Send a direct message to a specific node

--listen Monitor incoming messages in real time

Common Workflows

Back Up and Restore Your Config

# Export current config

meshtastic --export-config > my-config.yaml

# Restore after firmware update or factory reset

meshtastic --configure my-config.yaml

Set Up a Router Node

# Set role to Router

meshtastic --set device.role ROUTER

# Set region

meshtastic --set lora.region US

# Set TX power

meshtastic --set lora.tx_power 30

# Set a descriptive name

meshtastic --set-owner "NoDak-Fargo-RTR"

Configure a Channel with Custom PSK

# Set primary channel name and encryption key

meshtastic --ch-index 0 --ch-set name "NoDak"

meshtastic --ch-index 0 --ch-set psk random

# Add a secondary channel

meshtastic --ch-add "Emergency"

Flash Firmware from CLI

# Flash latest stable firmware

meshtastic --flash

# Flash a specific version

meshtastic --flash --firmware-version 2.x.x

See the firmware guide for full details on update methods and troubleshooting.

Meshtastic CLI vs MeshCore CLI

Both protocols have Python-based CLI tools, but they're separate packages with different commands.

Feature	Meshtastic CLI	MeshCore CLI
Install	`pip install meshtastic`	`pip install meshcore-cli`
Connection	Serial, BLE, TCP	Serial, BLE, TCP
Config format	Key-value flags (--set)	Subcommands (config set)
Config backup	YAML export/import	Per-command

See our MeshCore CLI guide if you're working with MeshCore devices.

Troubleshooting

"Command not found" after installing

Your Python scripts directory may not be in your PATH. Try python -m meshtastic instead, or add the pip scripts directory to your PATH (~/.local/bin on macOS/Linux).

"No Meshtastic devices found"

Check USB cable (data, not charge-only). Try specifying the port: meshtastic --port /dev/ttyUSB0 --info. Run ls /dev/tty* (Linux/Mac) or check Device Manager (Windows) to find the right port. Close the Meshtastic app first — only one connection at a time.

"Permission denied" on serial port (Linux)

Add your user to the dialout group: sudo usermod -a -G dialout $USER then log out and back in.

BLE connection issues

BLE can be flaky on some systems. Install pip install meshtastic[ble] for BLE support. Move closer to the device. If issues persist, use USB serial — it's always more reliable.