---
id: usage
title: Using the Meshtastic CLI
sidebar_label: Usage
slug: /software/python/cli/usage
sidebar_position: 2
---

This section covers using the "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the Meshtastic devices.

:::note
The `meshtastic` command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path).
:::

## Viewing Serial Output

The `--noproto` command in the Meshtastic Python CLI is used to disable the API and function merely as a "dumb serial terminal."  This mode of operation allows both the API and device functionalities to remain accessible for regular use, while simultaneously providing a window into the raw serial output. This feature can be particularly useful for debugging, development, or understanding the low-level communication between devices.

```shellsession title="Example Usage"
user@host % meshtastic --noproto
# You should see results similar to this:
WARNING file:mesh_interface.py _sendToRadio line:681 Not sending packet because protocol use is disabled by noProto
Connected to radio
WARNING file:mesh_interface.py _sendPacket line:531 Not sending packet because protocol use is disabled by noProto
INFO  | 18:38:04 711 [DeviceTelemetryModule] (Sending): air_util_tx=0.116361, channel_utilization=1.916667, battery_level=101, voltage=4.171000
DEBUG | 18:38:04 711 [DeviceTelemetryModule] updateTelemetry LOCAL
DEBUG | 18:38:04 711 [DeviceTelemetryModule] Node status update: 2 online, 4 total
INFO  | 18:38:04 711 [DeviceTelemetryModule] Sending packet to phone
INFO  | 18:38:04 711 Telling client we have new packets 28
```

## Getting a list of User Preferences

You can get a list of user preferences by running '--get' with an invalid attribute such as 'all'.

```shell
meshtastic --get all
```

## Changing settings

You can also use this tool to set any of the device parameters which are stored in persistent storage. For instance, here's how to set the device
to keep the Bluetooth link alive for eight hours (any usage of the Bluetooth protocol from your phone will reset this timer)

```shell title="Expected Output"
# You should see a result similar to this:
mydir$ meshtastic --set power.wait_bluetooth_secs 28800
Connected to radio...
Setting power.wait_bluetooth_secs to 28800
Writing modified preferences to device...
```

Or to set a node at a fixed position and never power up the GPS.

```shell
meshtastic --setlat 25.2 --setlon -16.8 --setalt 120
```

Or to configure an ESP32 based board to join a Wifi network as a station:

```shell
meshtastic --set network.wifi_ssid mywifissid --set network.wifi_psk mywifipsw --set network.wifi_enabled 1
```

:::note
For a full list of preferences which can be set (and their documentation) can be found in the [protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.User).
:::

### Changing channel settings

The channel settings can also be changed, either by using a standard (shareable) meshtastic URL or you can set a particular channel parameter (for advanced users).

:::warning
Meshtastic encodes the radio channel and PSK in the channel's URL. All nodes must connect to the channel again by using the URL provided after a change in this section by performing the `--info` switch.
:::

```shell
meshtastic --ch-set name mychan --ch-index 1 --info
```

You can even set the channel preshared key to a particular AES128 or AES256 sequence.

```shell
meshtastic --ch-index 1 --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
```

Use `--ch-set psk none --ch-index 0` to turn off encryption.

Use `--ch-set psk random --ch-index 0` to assign a new (high quality) random AES256 key to the primary channel (similar to what the Android app does when making new channels).

Use `--ch-set psk default --ch-index 0` to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.

All `ch-set` commands need to have the `ch-index` parameter specified:

```shell
meshtastic --ch-index 1 --ch-set name mychan --info
```

### Ham radio support

Meshtastic is designed to be used without a radio operator license. If you do have a license you can set your operator ID and turn off encryption with:

```shell title="Expected Output"
# You should see a result similar to this:
mydir$ meshtastic --set-ham KI1345
Connected to radio
Setting Ham ID to KI1345 and turning off encryption
Writing modified channels to device
```

Toggling `set-ham` changes your device settings in the following ways.

|   Setting    | `set-ham` Default |                               Normal Default                               |
| :----------: | :---------------: | :------------------------------------------------------------------------: |
| `IsLicensed` |      `true`       | See [User Config - IsLicensed](/docs/configuration/radio/user#is-licensed-ham) |
|  `LongName`  |  _Your CallSign_  |     See [User Config - LongName](/docs/configuration/radio/user#long-name)     |
| `ShortName`  |  _Abrv CallSign_  |    See [User Config - ShortName](/docs/configuration/radio/user#short-name)    |
|    `PSK`     |       `""`        |         See [Channel Settings - PSK](#changing-the-preshared-key)          |

## Changing the preshared key

You can set the channel preshared key to a particular AES128 or AES256 sequence.

```shell
meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
```

Use "--ch-set psk none" to turn off encryption.

Use "--ch-set psk random" will assign a new (high quality) random AES256 key to the primary channel (similar to what the Android app does when making new channels).

Use "--ch-set psk default" to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.

All "ch-set" commands will default to the primary channel at index 0, but can be applied to other channels with the "ch-index" parameter.

## Utilizing BLE via the Python CLI

The Python CLI supports communicating with Meshtastic devices via Bluetooth Low Energy (BLE), in addition to the standard serial and TCP/IP connections. To use BLE, you will need a Bluetooth adapter on your computer.

### Scan for BLE Devices

First, you can scan for available Meshtastic devices using:

```shell
meshtastic --ble-scan
```

This will list all Meshtastic devices discoverable over BLE along with their addresses and names in the following format:

```shell
Found: name='Meshtastic_1234' address='AA11BB22-CC33-DD44-EE55-FF6677889900'
BLE scan finished
```

### Available Commands

Once you have the device address or name, you can utilize it alongside your normal Python CLI commands like `--info`, `--nodes`, `--export-config`, etc. but with the `--ble` option to communicate via BLE rather than serial.

You can use **either** the name or address to issue your commands.

```shell
meshtastic --ble <name> --info
meshtastic --ble <address> --nodes
```

The initial time you use the `--ble` option for a specific device, you will be prompted to enter the BLE PIN code (as is normal with a client). Once paired, this step won't be required unless you forget the device.

:::note
On Linux, you may need to pair the BLE device using `bluetoothctl` before connecting. This allows entering the required PIN for pairing.
:::

### Additional BLE Examples

#### Scan for devices and get info from the first one:

```bash
meshtastic --ble-scan
# Sample output:
# Found: name='Meshtastic_1234' address='AA11BB22-CC33-DD44-EE55-FF6677889900'
# Found: name='Meshtastic_5678' address='FF00DD00-AA11-BB22-CC33-DD44EE5566FF'
BLE scan finished

meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --info
```

#### Connect to a named device and read the node list:

```shell
meshtastic --ble Meshtastic_1234 --nodes
```
#### Export device config with --export-config

```shell
meshtastic --ble Meshtastic_1234 --export-config > config.yaml
```

#### Send a command to a remote device using the --dest option:

```shell
meshtastic --dest '!fe1932db4' --set device.is_managed false --ble Meshtastic_9abc
```

#### For debugging, you can enable verbose BLE logging by adding the `--debug` flag:

```shell
meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --debug --info
```

## FAQ/common problems

This is a collection of common questions and answers from our friendly forum.

### Permission denied: ‘/dev/ttyUSB0’

As previously discussed on the [forum](https://meshtastic.discourse.group/t/question-on-permission-denied-dev-ttyusb0/590/3?u=geeksville)

This indicates an OS permission problem for access by your user to the USB serial port. Typically this is fixed by the following.

```shell
sudo usermod -a -G dialout <username>
```

If adding your user to the dialout group does not work, you can use the following command to find out which group to add your user to.
In this example (from Arch Linux) the group was "uucp"

```shell
❯ ls -al /dev/ttyACM0
crw-rw---- 1 root uucp 166, 0 Jul 20 21:52 /dev/ttyACM0
```

### Mac OS Big Sur

There is a problem with Big Sur and pyserial. The workaround is to install a newer version of pyserial:

```shell
pip3 install -U --pre pyserial
```