Meshtastic Python CLI Guide

The Meshtastic Python package provides both a command-line interface and a Python library for scripting. It is the primary tool for configuring nodes without the mobile app, backing up configurations, and automating tasks.

Installation

pip3 install --upgrade "meshtastic[cli]"

Requires Python 3.9 or newer (check the current meshtastic package requirements for the exact minimum). On Linux you may need to add your user to the dialout group to access serial ports without sudo:

sudo usermod -aG dialout $USER

Serial access: connect via USB at 115200 baud. The CLI auto-detects the port in most cases.

Getting Device Information

# Full device info: firmware, hardware, channel config, user info
meshtastic --info

# List all nodes heard by this device
meshtastic --nodes

Configuration Backup and Restore

# Export full configuration to YAML
meshtastic --export-config > config.yaml

# Restore configuration from YAML
meshtastic --configure config.yaml

Back up your configuration before any firmware update. The export includes all channel PSKs, radio settings, and module configuration. Because the exported YAML contains all channel PSKs in recoverable form, treat the backup file as secret — anyone with it can join and decrypt your private channels. Store it encrypted.

Setting Node Identity

# Set the node's display name
meshtastic --set-owner "MyName"

# Set a short name (4 chars, shown on small displays)
meshtastic --set-owner-short "MN01"

Radio Configuration

# Set LoRa region (required before use)
meshtastic --set lora.region US

# Set modem preset
meshtastic --set lora.modem_preset LONG_FAST

# Set TX power. 0 = use the region maximum (recommended); the firmware
# applies the correct per-region/per-board legal cap. 30 dBm (1 W) is the
# FCC Part 15 conducted ceiling for US 915 MHz, referenced to a 6 dBi
# antenna; with a higher-gain antenna you must reduce conducted power so
# EIRP stays compliant. Most hardware cannot reach 30 dBm regardless.
meshtastic --set lora.tx_power 0

# Set hop limit (default 3; max 7)
meshtastic --set lora.hop_limit 3

Device Role

# Set device role (use the bare enum value, with no _ROLE suffix)
meshtastic --set device.role CLIENT
meshtastic --set device.role CLIENT_MUTE
meshtastic --set device.role CLIENT_HIDDEN
meshtastic --set device.role TRACKER
meshtastic --set device.role LOST_AND_FOUND
meshtastic --set device.role SENSOR
meshtastic --set device.role TAK
meshtastic --set device.role TAK_TRACKER
meshtastic --set device.role ROUTER
meshtastic --set device.role ROUTER_LATE
meshtastic --set device.role REPEATER

Most ordinary nodes should be CLIENT. For fixed infrastructure use ROUTER (or ROUTER_LATE); REPEATER is deprecated as of firmware 2.7.11. There is no CLIENT_BASE role.

Channel Management

# Add a new channel (assigns next available index)
meshtastic --ch-add

# Name the channel you just added (e.g. index 1)
meshtastic --ch-index 1 --ch-set name MyPrivateChannel

# Enable MQTT uplink on channel 0
meshtastic --ch-index 0 --ch-set uplink_enabled true

# Enable MQTT downlink on channel 0
meshtastic --ch-index 0 --ch-set downlink_enabled true

# Set a custom PSK on channel 1. Use 'random' to generate one, or supply
# the raw base64 key string directly (no 'base64:' prefix).
meshtastic --ch-index 1 --ch-set psk random

Telemetry

# Set device metrics broadcast interval (seconds; default 1800 = 30 min)
meshtastic --set telemetry.device_update_interval 1800

# Set environment sensor interval (seconds)
meshtastic --set telemetry.environment_update_interval 1800

# Enable environment telemetry
meshtastic --set telemetry.environment_measurement_enabled true

Position

# Set fixed position (for nodes without GPS)
meshtastic --setlat 39.7392 --setlon -104.9903

# Set position broadcast interval (seconds; 0 = disable)
meshtastic --set position.position_broadcast_secs 3600

Sending Messages

# Send a message to all nodes on the primary channel
meshtastic --sendtext "Hello mesh"

# Send on a specific channel (index 1)
meshtastic --ch-index 1 --sendtext "Private message"

Serial Console (Advanced)

The Meshtastic device serial protocol uses length-delimited protobuf frames (ToRadio/FromRadio), not raw JSON commands — writing JSON bytes to the port will not configure the device. The CLI prints decoded packets as JSON to stdout for human reading only. For most users the Python CLI is the right tool; the snippet below is only a low-level illustration of opening the serial port:

import serial, json
ser = serial.Serial('/dev/ttyUSB0', 115200, timeout=1)
# Device control is via protobuf ToRadio frames; see the Meshtastic Python library source for details

Common CLI Patterns

# Full setup sequence for a new infrastructure node
meshtastic --set-owner "Tower-Node-01"
meshtastic --set lora.region US
meshtastic --set lora.modem_preset LONG_FAST
meshtastic --set device.role ROUTER
meshtastic --set lora.hop_limit 3
meshtastic --export-config > tower-node-01-config.yaml