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
Day-to-day messaging, full device configuration, map view, channel management
Browser-based interface at client.meshtastic.org: messaging and full configuration
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 --versionPlatform 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 --infoIf multiple devices are connected, specify the port: meshtastic --port /dev/ttyUSB0 --info
Bluetooth
Connect wirelessly via Bluetooth Low Energy.
meshtastic --ble --infoWith 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 --infoCommand 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, every setting and channel (local node only) |
| meshtastic --nodes | Table 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-config | Dump full device config as YAML |
| meshtastic --configure <file> | Apply config from a YAML file |
| meshtastic --enter-dfu | Put an nRF52 board into DFU mode for a UF2 update |
| meshtastic --factory-reset | Reset 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 loggingCommon 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.
| Feature | Meshtastic CLI | MeshCore CLI |
|---|---|---|
| Install | pipx install "meshtastic[cli]" | pipx install meshcore-cli (runs as meshcli) |
| Connection | Serial, BLE, TCP | Serial, BLE, TCP |
| Config format | Key-value flags (--set) | set <param> <value> commands |
| Config backup | YAML export/import | No 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.