meshtastic/docs/software/python-cli/index.mdx

---
id: python-cli
title: Meshtastic Python CLI Guide
slug: /software/python/cli
sidebar_label: Python CLI
sidebar_position: 4
---

The python pip package installs a "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the meshtastic devices. This command is not run inside of python, you run it from your operating system shell prompt directly. If when you type "meshtastic" it doesn't find the command and you are using Windows: Check that the python "scripts" directory is in your path.

## Connection Arguments

### --port PORT

The port the Meshtastic device is connected to, i.e. `/dev/ttyUSB0`, `/dev/cu.wchusbserial`, `COM4` etc. if unspecified, meshtastic will try to find it. Important to use when multiple devices are connected to ensure you call the command for the correct device.

This argument can also be specified as `--serial` or `-s`.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --info
meshtastic --port COM4 --info
meshtastic -s --info
```

### --host HOST

The hostname/ipaddr of the device to connect to (over TCP). If a host is not provided, the CLI will try to connect to `localhost`.

This argument can also be specified as `--tcp` or `-t`.

```shell title="Usage"
meshtastic --host meshtastic.local --info
meshtastic --host --info
```

### --ble BLE

Connect to a Meshtastic device using its BLE address or name. This option allows for wireless communication with the device, similar to how the `--host` option is used for TCP connections. If an address is not provided, meshtastic will try to find a compatible device that's paired.

This argument can also be specified as `-b`.

```shell title="Usage"
meshtastic --ble "device_name_or_address" --info
meshtastic -b --info
```

## Help & Support Arguments

### -h or --help

Shows a help message that describes the arguments.

```shell title="Usage"
meshtastic -h
```

### --version

Show program's version number and exit.

```shell title="Usage"
meshtastic --version
```

### --support

Print out info that would be helpful supporting any issues.

```shell title="Usage"
meshtastic --support
```

## Optional Arguments

### --export-config

Export the configuration of the device. (to be consumed by the '--configure' command).

To create to a file with the connected device's configuration, this command's output must be piped to a yaml file.

```shell title="Usage"
meshtastic --export-config > example_config.yaml
```

### --configure

Configure radio using a yaml file.

```shell title="Usage"
meshtastic --configure example_config.yaml
```

### --seriallog SERIALLOG

Logs device serial output to either 'stdout', 'none' or a filename to append to. Defaults to 'stdout' if no filename is specified.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --seriallog
meshtastic -t meshtastic.local --seriallog log.txt
```

### --info

Read and display the radio config information.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --info
```

### --set-canned-message

Set the canned message plugin messages separated by pipes `|` (up to 200 characters).

```shell title="Usage"
meshtastic --set-canned-message "I need an alpinist!|Call Me|Roger Roger|Keep Calm|On my way"
```

### --get-canned-message

Show the canned message plugin message.

```shell title="Usage"
meshtastic --get-canned-message
```

### --set-ringtone RINGTONE

Set the Notification Ringtone (up to 230 characters).

```shell title="Usage"
meshtastic --set-ringtone "LeisureSuit:d=16,o=6,b=56:f.5,f#.5,g.5,g#5,32a#5,f5,g#.5,a#.5,32f5,g#5,32a#5,g#5,8c#.,a#5,32c#,a5,a#.5,c#.,32a5,a#5,32c#,d#,8e,c#.,f.,f.,f.,f.,f,32e,d#,8d,a#.5,e,32f,e,32f,c#,d#.,c#"
```

### --get-ringtone

Show the stored ringtone.

```shell title="Usage"
meshtastic --get-ringtone
```

### --nodes

Prints a node list in a pretty, formatted table.

```shell title="Usage"
meshtastic --nodes
```

### --qr

Displays the URL and QR code that corresponds to the current primary channel.

```shell title="Usage"
meshtastic --qr
```

### --qr-all

Displays the URL and QR code that corresponds to all configured channels on the node.

```shell title="Usage"
meshtastic --qr-all
```

### --get [config_section]

Gets a preferences field.

Configuration values are described in: [Configuration](https://meshtastic.org/docs/configuration).

```shell title="Usage"
meshtastic --get lora
meshtastic --get lora.region
```

To see all valid values, pass an invalid value, such as `0`:

```shell title="Usage"
meshtastic --get 0
```

### --set [config_section].[option]  [value]

Sets a preferences field.

Configuration values are described in: [Configuration](https://meshtastic.org/docs/configuration).

```shell title="Usage"
meshtastic --set lora.region Unset
```

### --seturl SETURL

Set the channel URL, which contains LoRa configuration plus the configuration of channels. Replaces your current configuration and channels completely.

```shell title="Usage"
meshtastic --seturl https://www.meshtastic.org/c/GAMiIE67C6zsNmlWQ-KE1tKt0fRKFciHka-DShI6G7ElvGOiKgZzaGFyZWQ=
```

### --pos-fields POS_FIELDS

Configure position fields to send with positions; can pass multiple values. With 0 values, list current settings.

```shell title="Usage"
meshtastic --pos-fields
meshtastic --pos-fields ALTITUDE HEADING SPEED
```

### --ch-index CH_INDEX

Act on the specified channel index. Applies to options that configure channels (such as `--ch-set` and `--ch-del`) as well as options that send messages to the mesh (such as `--sendtext` and `--traceroute`).

```shell title="Usage"
meshtastic --ch-index 1 --ch-disable
```

### --ch-add CH_ADD

Add a secondary channel, you must specify a channel name.

Incompatible with `--ch-index`. If you pass `--ch-add`, any subsequent `--ch-set` and other commands that use a channel will use the index of the newly-added channel.

```shell title="Usage"
meshtastic --ch-add testing-channel
```

### --ch-del

Delete the channel specified by `--ch-index`.

```shell title="Usage"
meshtastic --ch-index 1 --ch-del
```

### --ch-enable (deprecated)

This option is deprecated. Using `--ch-add` is preferred in order to ensure there are no gaps in the channel list.

Enable the channel specified by `--ch-index`.

```shell title="Usage"
meshtastic --ch-index 1 --ch-enable
```

### --ch-disable (deprecated)

This option is deprecated. Using `--ch-del` is preferred in order to ensure there are no gaps in the channel list.

Disable the channel specified by `--ch-index`.

```shell title="Usage"
meshtastic --ch-index 1 --ch-disable
```

### --ch-set CH_SET CH_SET

Set a channel parameter on the channel specified by `--ch-index`.

```shell title="Usage"
meshtastic --ch-set id 1234 --ch-index 0
```

### --ch-vlongslow

Change modem preset to `VERY_LONG_SLOW`.

```shell title="Usage"
meshtastic --ch-vlongslow
```

### --ch-longslow

Change modem preset to `LONG_SLOW`.

```shell title="Usage"
meshtastic --ch-longslow
```

### --ch-longfast

Change modem preset to (the default) `LONG_FAST`.

```shell title="Usage"
meshtastic --ch-longfast
```

### --ch-medslow

Change modem preset to `MEDIUM_SLOW`.

```shell title="Usage"
meshtastic --ch-medslow
```

### --ch-medfast

Change modem preset to `MEDIUM_FAST`.

```shell title="Usage"
meshtastic --ch-medfast
```

### --ch-shortslow

Change modem preset to `SHORT_SLOW`.

```shell title="Usage"
meshtastic --ch-shortslow
```

### --ch-shortfast

Change modem preset to `SHORT_FAST`.

```shell title="Usage"
meshtastic --ch-shortfast
```

### --set-owner SET_OWNER

Set device owner name, sometimes called the long name.

```shell title="Usage"
meshtastic --set-owner "MeshyJohn"
```

### --set-owner-short SET_OWNER_SHORT

Set device owner short name (4 characters max).

```shell title="Usage"
meshtastic --set-owner-short "MJ"
```

### --set-ham SET_HAM

Set licensed Ham ID (by setting the owner name) and turn off encryption on the primary channel.

To disable Ham mode, use `--set-owner` and `--set-owner-short` to reset the owner names, and use `--seturl` or `--ch-set` commands to configure channels with the name and encryption you wish them to have. Or, use `--factory-reset` to reset to default settings.

```shell title="Usage"
meshtastic --set-ham KI1345
```

### --dest DEST

The destination node id for any sent commands, if not passed to a command another way.  Used for [Remote Node Administration](/docs/configuration/remote-admin).

On many shells, exclamation points trigger special behavior unless enclosed in single quotes.

```shell title="Usage"
meshtastic --dest '!28979058' --set-owner "MeshyJohn"
```

### --sendtext SENDTEXT

Send a text message. Can specify a channel index (`--ch-index`) and/or a destination (`--dest`).

```shell title="Usage"
meshtastic --sendtext 'Hello Mesh!'
meshtastic --ch-index 1 --sendtext 'Hello secondary channel!'
```

### --traceroute TRACEROUTE

Traceroute from connected node to a destination. You need pass the destination ID as an argument, and may pass `--ch-index` to specify a channel. The node you are tracing must have the same channel configured, and only nodes that share the channel will identify themselves within the response. With recent enough firmware, other nodes may be included as `!ffffffff` but not with their actual ID.

```shell title="Usage"
meshtastic --traceroute '!ba4bf9d0'
```

### --request-telemetry

Request telemetry from a node. You need to pass the destination ID as an argument with `--dest`. For repeaters, using the node's decimal ID may be more effective, but a hexadecimal ID should work as well.

```shell title="Usage"
meshtastic --request-telemetry --dest '!ba4bf9d0'
meshtastic --request-telemetry --dest 1828779180
```

### --request-position

Request position from a node. You need to pass the destination ID as an argument with `--dest`.

```shell title="Usage"
meshtastic --request-position --dest '!ba4bf9d0' --ch-index 1
```

### --ack

Used in combination with `--sendtext` and other commands to wait for an acknowledgment. Not all commands will be able to return an acknowledgment. Best used for commands that specify a single destination node.

```shell title="Usage"
meshtastic --sendtext 'Hello Mesh!' --dest '!28979058' --ack
```

### --reboot

Tell the node to reboot.

```shell title="Usage"
meshtastic --reboot
```

### --shutdown

Tell the node to shutdown.

```shell title="Usage"
meshtastic --shutdown
```

### --factory-reset

Tell the node to install the default config.

```shell title="Usage"
meshtastic --factory-reset
```

### --reset-nodedb

Tell the node to clear its list of nodes.

```shell title="Usage"
meshtastic --reset-nodedb
```

### --remove-node NODE

Tell the node to remove the specified node from the NodeDB.

```shell title="Usage"
meshtastic --remove-node '!48759737'
```

### --reply

Listen for messages. When one is received, send a message to the primary channel repeating the message along with some information.

```shell title="Usage"
meshtastic --reply
```

### --no-time

Suppress sending the current time to the mesh on startup. May improve reliability and startup time.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --no-time
```

### --no-nodes

Instruct the node to not send nodeinfo from the NodeDB on startup. Requires firmware of sufficient version. Commands that use node information may behave unpredictably, since that information will not be populated, but this can improve efficiency for commands that don't.

```shell title="Usage"
meshtastic --no-nodes --no-time --sendtext "Firing off a quick message"
```

### --wait-to-disconnect WAIT_TO_DISCONNECT

After performing whatever actions are specified by other options, wait before disconnecting from the device. Some devices will reboot when the serial connection disconnects, so adding a wait time may improve reliability. Defaults to 5 seconds if not provided.

```shell title="Usage"
meshtastic --set lora.channel_num 20 --wait-to-disconnect 10
```

### --setalt SETALT

Set device altitude (allows use without GPS), and enables fixed position mode.

Can only be used on locally-connected nodes and not along with `--dest`.

```shell title="Usage"
meshtastic --setalt 120
```

### --setlat SETLAT

Set device latitude (allows use without GPS), and enables fixed position mode.

Can only be used on locally-connected nodes and not along with `--dest`.

```shell title="Usage"
meshtastic --setlat 25.2
```

### --setlon SETLON

Set device longitude (allows use without GPS), and enables fixed position mode.

Can only be used on locally-connected nodes and not along with `--dest`.

```shell title="Usage"
meshtastic --setlon -16.8
```

### --remove-position

Clear the node's currently set fixed position and disable fixed position mode.

Can only be used on locally-connected nodes and not along with `--dest`.

```shell title="Usage"
meshtastic --remove-position
```

### --debug

Show API library debug log messages.

```shell title="Usage"
meshtastic --debug --info
```

### --listen

Stay open and listen to the stream of protocol buffer messages. This option enables `--debug` even if it is not provided alongside this argument.

```shell title="Usage"
meshtastic --listen
```

### --test

Run stress test against all connected Meshtastic devices.

```shell title="Usage"
meshtastic --test
```

### --ble-scan

Scan for available Meshtastic devices using BLE. This command lists discoverable devices, providing a convenient method to identify devices for connection via BLE.

```shell title="Usage"
meshtastic --ble-scan
```

### --noproto

Don't start the API, just function as a dumb serial terminal. Useful for debugging because it doesn't count as a client. Depends on a physically cabled serial connection. It will connect but not display information over a network (--host) or Bluetooth (--ble) connection.

```shell title="Usage"
meshtastic --noproto
```

## Remote Hardware arguments

### --gpio-wrb GPIO_WRB GPIO_WRB

Set a particular GPIO # to 1 or 0.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest '!28979058'
```

### --gpio-rd GPIO_RD

Read from a GPIO mask.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest '!28979058'
```

### --gpio-watch GPIO_WATCH

Start watching a GPIO mask for changes.

```shell title="Usage"
meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest '!28979058'
```

## Tunnel arguments

### --tunnel

Linux only, very experimental. Low bandwidth and low reliability.

Create a TUN tunnel device for forwarding IP packets over the mesh.

## --subnet TUNNEL_NET

Set the subnet for the local end of the tunnel established using `--tunnel`.