Skip to content

Search guides, devices and posts

Back to Meshtastic

Meshtastic CLI Guide

The Meshtastic Python CLI reads and changes every setting from a terminal, and adds what the apps don't: YAML backups, batch changes, remote admin and scripting. Install it with pip or pipx, connect over USB, Bluetooth or the network, and you're running.

Checked October 2026 against Meshtastic 2.7.26 (stable), Meshtastic 2.8.1 (alpha) and Meshtastic Python CLI 2.7.11.

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, back up and restore configs, or integrate Meshtastic into larger systems.

The CLI talks to your device over USB serial (most common), Bluetooth, or TCP. It can read and change every setting, and adds things the apps don't, like YAML backups and scripting.

CLI vs App vs Web Client

Mobile App

Day-to-day messaging, full device configuration, map view, channel management

Web Client

Browser-based interface at client.meshtastic.org: messaging and full configuration

Python CLI

Config export/import, batch operations, remote management, Wi-Fi OTA updates, scripting

Installation

Prerequisites

  • Python 3.9 or newer
  • pip, or pipx (recommended on macOS and Linux)
  • On some ESP32 boards, a USB serial driver (CP210x or CH9102/CH34x). nRF52 and RP2040 boards usually need none.

Install

pip3 install --upgrade "meshtastic[cli]"

If pip refuses with an externally-managed-environment error (common on macOS and current Linux), use pipx: pipx install "meshtastic[cli]", then pipx ensurepath. Keep the quotes; without them zsh rejects the brackets. The [cli] part adds extras such as QR code output.

Verify the installation:

meshtastic --version

Platform Notes

macOS

Recent macOS includes the CH34x driver; Meshtastic's docs say to remove a separately downloaded one. Use brew install python if needed. If meshtastic isn't found after a pipx install, run pipx ensurepath and open a new terminal. Ports look like /dev/cu.usbmodem… or /dev/cu.wchusbserial….

Windows

ESP32 boards may need the CP210x or CH9102 driver. Run from Command Prompt or PowerShell; ports look like COM4. 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 (uucp on Arch): 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

With no name, it connects only if it finds exactly one device. Run meshtastic --ble-scan first, then use the exact name it prints: meshtastic --ble "Meshtastic_1234" --info. The first connection asks for the Bluetooth PIN.

TCP/IP (Network)

Connect to a device over the network, such as an ESP32 on Wi-Fi. The default port is 4403; --host 192.168.1.100:4403 sets one explicitly.

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

CommandWhat It Does
meshtastic --infoDevice info, firmware version, every setting and channel (local node only)
meshtastic --nodesTable of known nodes: role, battery, SNR, hops, last heard
meshtastic --set <key> <val>Change a config value
meshtastic --get <key>Read a config value
meshtastic --sendtext "msg"Send a text message on the primary channel
meshtastic --export-configDump full device config as YAML
meshtastic --configure <file>Apply config from a YAML file
meshtastic --enter-dfuPut an nRF52 board into DFU mode for a UF2 update
meshtastic --factory-resetReset settings to defaults, keeping keys and Bluetooth pairings

Info & Diagnostics

--info Owner, firmware and hardware, the node list, every setting and channel with its key. Don't post the output publicly.
--nodes Table of known nodes: ID, hardware, role, position, battery, channel use, SNR, hops and last heard. --show-fields picks columns.
--qr QR code and URL for the primary channel; --qr-all for every channel. The code includes the keys.

Configuration

--set <key> <val> Set a config value (e.g., --set device.role CLIENT_BASE). snake_case and camelCase both work; values like US and ROUTER are case-sensitive.
--get <key> Read a specific config value
--export-config Export the whole configuration as YAML, including the private key and channel keys. Keep the file private.
--configure <file> Apply configuration from a YAML file
--factory-reset Reset settings to defaults, keeping keys and pairings. --factory-reset-device also clears those.

Channel Management

--ch-index <N> --ch-set <key> <val> Configure a channel (name, psk, uplink_enabled, downlink_enabled)
--ch-add <name> Add a secondary channel with a random key (name up to 10 characters; can't be combined with --ch-index)
--ch-del Delete a channel (needs --ch-index; the primary can't be deleted)

See the channels guide for detailed channel and MQTT configuration.

Messaging

--sendtext "message" Send on the primary channel, or another with --ch-index
--dest '!a1b2c3d4' --sendtext "msg" Direct message to one node. Quote the ID: the ! means something to the shell.
--listen Stay connected and print the raw packet stream with debug logging

Common Workflows

Back Up and Restore Your Config

# Export current config (includes the private key; keep it safe)

meshtastic --export-config my-config.yaml

# Restore after firmware update or factory reset

meshtastic --configure my-config.yaml

Set Up a Fixed Node

# Region first: no region, no transmit (and on 2.8, no keys)

meshtastic --set lora.region US

# 0 = the maximum legal power for the region

meshtastic --set lora.tx_power 0

# Names: long, and a short one (up to 4 characters)

meshtastic --set-owner "Hilltop Relay" --set-owner-short HTOP

# Role last. CLIENT_BASE for a home node; ROUTER only for a truly strategic site

meshtastic --set device.role CLIENT_BASE

On ESP32, ROUTER turns on power saving and Bluetooth goes quiet, so set it last. Which role fits is in our device roles guide.

Add a Private Channel

# Secondary channel with a random 256-bit key

meshtastic --ch-add "Family"

# QR codes for every channel, to share in person

meshtastic --qr-all

Keep private groups on a secondary channel. Renaming the primary channel moves your node to a different frequency slot, and changing its key stops you reading the local mesh. See the channels guide.

Manage a Remote Node with Admin Keys

# 1. On the node you'll manage from: get its public key

meshtastic --get security.public_key

# 2. On the remote node (over USB, once): add that key

meshtastic --set security.admin_key "base64:PASTEKEYHERE"

# 3. From then on, over the mesh

meshtastic --dest '!a1b2c3d4' --set lora.tx_power 0

Up to three admin keys; setting it again appends, and 0 clears the list. The old "admin" channel only works if security.admin_channel_enabled is turned on. --info, --nodes, --export-config and --configure only work on the node you're connected to.

Firmware Updates from the CLI

The CLI doesn't flash firmware over USB; use the web flasher or the install scripts in each release. It can do these two things:

# ESP32 on Wi-Fi, firmware 2.7.18 or newer: OTA update

meshtastic --host 192.168.1.50 --ota-update firmware.bin

# nRF52: enter DFU mode, then copy the .uf2 to the drive that appears

meshtastic --enter-dfu

See the firmware guide for every update method and troubleshooting.

Meshtastic CLI vs MeshCore CLI

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

FeatureMeshtastic CLIMeshCore CLI
Installpipx install "meshtastic[cli]"pipx install meshcore-cli (runs as meshcli)
ConnectionSerial, BLE, TCPSerial, BLE, TCP
Config formatKey-value flags (--set)set <param> <value> commands
Config backupYAML export/importNo full export; settings are read with get

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. If you installed with pipx, run pipx ensurepath and open a new terminal.

"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), ls /dev/cu.* (macOS) or check Device Manager (Windows) to find the right port. Only one program can use a serial port at a time, so close the web client, a flasher tab or any serial monitor first.

"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

Bluetooth support is built in; there's no separate package. Run meshtastic --ble-scan to see the exact device name, and enter the PIN on first connection. On Linux you may need to pair with bluetoothctl first. If it stays unreliable, USB serial is the dependable option.