Meshtastic CLI Reference

Meshtastic Python CLI Guide
Complete Meshtastic CLI Command Reference

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

Complete Meshtastic CLI Command Reference

The Meshtastic Python CLI provides the most comprehensive access to node configuration and data. This reference covers all major command categories.

Installation

pip3 install --upgrade "meshtastic[cli]"
# or for the latest pre-release version:
pip3 install --upgrade --pre "meshtastic[cli]"

Connection Options

# Auto-detect serial port (most common):
meshtastic --info

# Specify serial port (Windows):
meshtastic --port COM3 --info

# Specify serial port (Linux/Mac):
meshtastic --port /dev/ttyUSB0 --info

# Connect via TCP (WiFi-enabled nodes):
meshtastic --host 192.168.1.100 --info

# Connect via BLE. First scan to find the real device name/address:
meshtastic --ble-scan
# then connect using the name or address it reports:
meshtastic --ble "Meshtastic_ABCD" --info

Information and Status

# Show device info, config, and channels:
meshtastic --info

# Show node database (all known nodes):
meshtastic --nodes

# View channels: --info lists them; --qr-all shows channel URLs/QR codes:
meshtastic --qr-all

Configuration Get/Set

# Get a specific config value:
meshtastic --get device.role
meshtastic --get lora.hop_limit
meshtastic --get power.is_power_saving

# Set a config value (role values are bare enum names: CLIENT, ROUTER, ROUTER_LATE, CLIENT_MUTE, etc. - no _ROLE suffix):
meshtastic --set device.role ROUTER
meshtastic --set lora.hop_limit 5
meshtastic --set lora.region US

# Set multiple values at once:
meshtastic --set device.role ROUTER --set lora.hop_limit 5 --set power.is_power_saving false

Channel Management

# Show current channels:
meshtastic --info # includes channel list

# Set channel 0 (primary) name and key:
meshtastic --ch-index 0 --ch-set name "CommunityMesh"
meshtastic --ch-index 0 --ch-set psk "base64key=="

# Add a new channel:
meshtastic --ch-add

# Delete channel (specify index):
meshtastic --ch-del --ch-index 2

# Enable/disable MQTT uplink per channel:
meshtastic --ch-index 0 --ch-set uplink_enabled true
meshtastic --ch-index 0 --ch-set downlink_enabled true

Caution: Channel 0 is the default public channel. Enabling downlink_enabled on it lets anyone on the public MQTT broker inject messages into your local mesh; enabling uplink_enabled publishes that channel's traffic publicly. Note also that Meshtastic uploads packets to the broker unencrypted by default even on a channel with a PSK unless mqtt.encryption_enabled is set true. Only enable uplink/downlink on channels you intend to bridge.

Identity

# Set long name:
meshtastic --set-owner "Your Name"

# Set short name (4 chars max):
meshtastic --set-owner-short "AB01"

Position

# Set fixed GPS position (latitude and longitude):
meshtastic --setlat 45.5051 --setlon -122.6750

# Remove fixed position (use live GPS):
meshtastic --remove-position

The CLI sets a fixed position with --setlat and --setlon only; there is no --setalt flag. To set altitude as well, use the Python API (interface.localNode.setFixedPosition(lat, lon, alt)).

Messaging

# Send a text message to primary channel:
meshtastic --sendtext "Hello, mesh!"

# Send to a specific channel index:
meshtastic --ch-index 1 --sendtext "Admin message"

# Listen for incoming messages and packets (Ctrl+C to stop):
meshtastic --listen

Waypoints are created from the mobile/desktop apps. The CLI does not provide a --sendwaypoint / --waypoint-* set of flags as a documented way to send a waypoint.

Maintenance

# Export full config to file (output is YAML):
meshtastic --export-config > config.yaml

# Restore/apply config from a YAML file:
meshtastic --configure config.yaml

# Factory reset (clears all config and node DB):
meshtastic --factory-reset

# Reboot device:
meshtastic --reboot

There is no --import-config flag. The output of --export-config is YAML (not JSON), and it is applied back with --configure.