MESHCORE-CLI(1)

NAME
meshcore-cli - CLI interface to MeshCore companion app over BLE, TCP or Serial

SYNOPSIS
meshcore-cli [options] [commands...]
meshcli [options] [commands...]

DESCRIPTION
meshcore-cli (also available as meshcli) connects to a MeshCore companion radio node over BLE, TCP or serial and lets you interact with it from a terminal using a command line interface.

Commands can be passed as arguments on the command line (for scripting or one-shot use), or entered interactively when no command is given. In interactive mode (chat mode) you can enter a contact — another client, a repeater, a sensor or a room — and interact with it. For clients this means sending and receiving messages; for repeaters, rooms and sensors you get the remote CLI directly (you can still send messages to rooms using the msg command or a double-quote prefix).

A dedicated serial repeater mode is enabled with -r and connects directly to repeater hardware over UART, adding line editing, history, completion, clock sync and region file transfer.

Note: most MeshCore companion nodes are compiled with only one transport interface (BLE, serial, or TCP), so you must use the matching connection option.

OPTIONS

-h  Print help and exit.

-v  Print version and exit.

-j  JSON output mode. Disables init file execution.

-D  Enable debug output.

-S  Scan for BLE/serial devices and show an interactive device selector.

-l  List available BLE/serial devices and exit.

-T timeout
    Timeout in seconds for BLE scan (used with -S and -l). Default is 2 seconds.

-a address
    Specify device address or name to connect to.

-d name
    Filter MeshCore devices by name or address.

-P  Force pairing via the OS.

-t hostname
    Connect via TCP/IP to the given hostname.

-p port
    TCP port number. Default is 5000.

-s port
    Use the given serial port.

-b baudrate
    Set the serial baud rate.

-r  Serial repeater mode. Connects directly to repeater firmware via UART, adds line editing, history, completion, clock sync and region file transfer.

-C  Toggle classic mode for the prompt.

-c on|off
    Disable most colour output when set to off.

COMMANDS
Commands are given after the options on the command line. They can be chained. Many commands have short aliases. Prefixing a command with . (a dot) forces JSON output for that command regardless of the global -j flag. Use ?cmd for additional help on a specific command.

  General

chat
    Enter interactive (chat) mode.

chat_to contact
    Enter chat mode with the named contact.

script filename
    Execute commands from a file.

infos (alias: i)
    Print information about the node.

self_telemetry (alias: t)
    Print own telemetry.

card (alias: e)
    Export this node's URI.

ver (alias: v)
    Show firmware version.

reboot
    Reboot the node.

sleep secs (alias: s)
    Sleep for the given number of seconds.

wait_key (alias: wk)
    Wait until the user presses Enter.

apply_to filter commands (alias: at)
    Send commands to all contacts matching filter. See BATCH OPERATIONS below.

  Messaging

msg name message (alias: m, shorthand {)
    Send a message to a node by name.

wait_ack (alias: wa, shorthand })
    Wait for an acknowledgement of the last sent message.

chan number message (alias: ch)
    Send a message to channel number.

public message (alias: dch)
    Send a message to the public channel (channel 0).

recv (alias: r)
    Read the next message.

wait_msg (alias: wm)
    Wait for a message and read it.

sync_msgs (alias: sm)
    Fetch all unread messages from the node.

msgs_subscribe (alias: ms)
    Display messages as they arrive (subscribe mode).

get_channels
    Print information about all channels.

get_channel n
    Get info for a channel by number or name.

set_channel n name key
    Set channel info (number, name, key).

remove_channel n
    Remove a channel by number or name.

scope s
    Set the node's flood scope.

  Management

advert (alias: a)
    Send an advertisement now.

floodadv
    Flood advertisement.

get param
    Get a parameter value. Use get help for available parameters.

set param value
    Set a parameter value. Use set help for available parameters.

time epoch
    Set the device time to the given Unix epoch.

clock
    Get the current device time.

clock sync  (alias: st)
    Synchronise the device clock to the host time.

node_discover filter (alias: nd)
    Discover nodes filtered by type.

  Contacts

contacts / list (alias: lc)
    List all contacts.

reload_contacts (alias: rc)
    Force a reload of all contacts.

contact_info contact (alias: ci)
    Print information for the named contact.

contact_timeout contact value
    Set a temporary default timeout for a contact.

share_contact contact (alias: sc)
    Share a contact with others.

export_contact contact (alias: ec)
    Get a contact's URI.

import_contact URI (alias: ic)
    Import a contact from its URI.

remove_contact contact
    Remove a contact from this node.

path contact
    Display the path to a contact.

disc_path contact (alias: dp)
    Discover a new path and display it.

reset_path contact (alias: rp)
    Reset the path to a contact to flood.

change_path contact path (alias: cp)
    Change the path to a contact.

change_flags contact flags (alias: cf)
    Change contact flags (tel_l|tel_a|star).

req_telemetry contact (alias: rt)
    Print telemetry data for the contact as JSON.

req_mma contact (alias: rm)
    Request min/max/average values from a sensor.

req_acl contact
    Request the access control list for a sensor.

pending_contacts
    Show the list of pending contacts.

add_pending contact
    Manually add a pending contact.

flush_pending
    Flush the pending contact list.

  Repeater Commands (Client Mode)
The following commands send MeshCore protocol messages to a repeater via the companion node (BLE/TCP/serial without -r).

login name password (alias: l)
    Log into a repeater with the given password.

logout name
    Log out of a repeater.

cmd name command (alias: c, shorthand [)
    Send a raw command to a repeater (no acknowledgement).

wmt8 (shorthand ])
    Wait for a message reply with a timeout.

req_status name (alias: rs)
    Request status from a node.

req_neighbours name (alias: rn)
    Request the neighbour list in binary form.

trace path
    Run a trace; path is a comma-separated list of nodes.

INTERACTIVE MODE
Interactive (chat) mode is entered automatically when no command is given. It provides a prompt with the node name, command history and tab completion.

The to command selects the recipient for subsequent commands:

to dest
    Enter dest (node or channel).

to / or to ~
    Return to the root (your own node).

to ..
    Switch to the previously visited node (1-deep history).

to !
    Switch to the node from which the last message was received.

When you are inside a chat node the default action is to send messages. Inside a repeater or room server, input is forwarded as commands. To send a message to a room, prefix it with (double-quote) or use the msg command.

The / character bypasses the currently selected node:

/cmd
    Issue cmd on the root node.

/node/cmd
    Send cmd to the named node.

/dest msg
    Send msg to dest (channel or node).

  Flood Scope
Flood scope (available from firmware v1.10.0) limits packet propagation to named regions. On entering interactive mode the scope is reset to * (classic flood). Use the scope command or postfix the to command with %scope to change it. A scope can also be applied to a single command by prepending %scope (e.g. login%#Morbihan).

  Channel Echoes
When enabled with /set channel_echoes on, all channel messages are printed together with the SNR and the path taken. Sent messages show repeats from zero-hop repeaters; received messages show all path instances that reached your node.

REPEATER COMMANDS
meshcore-cli can reach repeaters via two fundamentally different paths.

  Serial Direct Mode (-r -s port)
Connects USB directly to the repeater hardware. The CLI speaks to the firmware's text CLI over UART.

  Client Mode (to <repeater>)
Connects to the companion node (BLE, TCP or serial without -r), then sends commands over the mesh radio using encrypted MeshCore cmd messages.

  Commands Available in Both Modes

ver, board, clock
    Information commands.

stats-core, stats-radio, stats-packets, clear stats
    Statistics.

neighbors, neighbor.remove n, discover.neighbors, advert
    Network management.

log start/log stop
    Enable or disable packet logging. In client mode log data is returned as RX_LOG_DATA events with rich packet parsing. In serial mode it is printed as raw firmware text.

get param / set param value
    Get or set configuration parameters: name, role, radio, freq, tx, af, repeat, public.key, lat, lon, advert.interval, flood.advert.interval, flood.max, guest.password, allow.read.only, owner.info, acl, rxdelay, txdelay, direct.txdelay, bridge.enabled, bridge.delay, bridge.source, bridge.baud, bridge.secret.

region [sub-command]
    Region management: save, home, get, put, remove, allowf, denyf.

gps on|off, gps sync, gps setloc, gps advert none|share|prefs
    GPS control.

sensor list/sensor get/sensor set
    Sensor management.

password pwd, powersaving on|off, setperm keyperm
time epoch, reboot, erase
    Miscellaneous commands.

  Serial-Only Commands (-r)

log Dump stored log file to the console.

log erase
    Erase the stored log file.

region upload file (alias: region load file)
    Upload a regions configuration from a local file to the node.

region download file
    Download the regions configuration from the node to a local file.

region list
    List allowed and denied regions.

tempradio
    Temporary radio configuration.

script file
    Execute a local script file (lines sent one by one over serial).

clock sync
    Sync the repeater clock to the host time (meshcore-cli intercepts this and sends time epoch to the firmware).

  Client-Mode-Only Commands

login pwd (alias: l)
    Log into the repeater.

logout
    Log out of the repeater.

req_status (alias: rs), req_neighbours (alias: rn)
req_regions (alias: rr), req_owner (alias: ro)
req_clock, req_acl (alias: ra)
    Binary protocol requests.

trace (alias: tr), dtrace (alias: dt)
    Path tracing via the mesh.

Contact operations:
    contact_info, path, disc_path, reset_path, change_path, change_flags, share_contact, export_contact, req_telemetry, forget_password, set timeout, get timeout.

clkreboot, start ota, get telemetry, get status, get acl
    Special operations.

: cmd
    Force send as a raw cmd message (e.g. :ver).

send msg / "msg
    Send a text message to the repeater or room.

BATCH OPERATIONS
apply_to filter commands

Sends commands to all contacts matching filter. The filter is a comma-separated list of conditions:

u<timestamp or u>timestamp
    Match by modification time relative to a timestamp. Append d, h, or m for days, hours or minutes ago (e.g. u<2d).

t=type
    Match by type: 1 client, 2 repeater, 3 room, 4 sensor.

h=n / h<n / h>n
    Match by number of hops.

d   Direct contacts only (equivalent to h>-1).

f   Flood contacts only (equivalent to h<0 or h=-1).

Commands should be written as in interactive mode. When writing from the command line, use commas to delimit filter fields clearly.

Chainable commands include contact_name (alias cn), reset_path (alias rp), forget_password (alias fp), and sleep.

CONFIGURATION
Configuration files are stored in $HOME/.config/meshcore.

If the directory exists, the default BLE address and command history are stored there.

If a file named init exists in this directory it is executed automatically just before any commands given on the command line (after option parsing).

Per-device init files named device-name.init are also supported. These are useful for setting per-contact timeouts with contact_timeout for contacts behind bridges.

EXAMPLES

Get information from the first BLE MeshCore device found:

        meshcore-cli -d "" infos

Get the current device time:

        meshcli -a C2:2B:A1:D5:3E:B6 clock

Get the time as JSON:

        meshcli -j -a C2:2B:A1:D5:3E:B6 clock

Chain commands: reboot, then sync and verify the clock:

        meshcli -j clock "clock sync" clock | jq -c

Send a message and wait for acknowledgement:

        meshcli msg Techo_fdl "Hello T-Echo" wa

Fetch all unread messages from a specific device:

        meshcli -d Techo sm

Enter interactive chat mode:

        meshcli chat

Remove all clients not seen in the last 2 days:

        meshcli at u<2d,t=1 remove_contact

Connect to a repeater directly over serial:

        meshcli -r -s /dev/ttyUSB0 clock

FILES

$HOME/.config/meshcore/
    Configuration directory. Created manually; meshcore-cli will use it if present.

$HOME/.config/meshcore/init
    Global init script executed before command-line commands.

$HOME/.config/meshcore/<device-name>.init
    Per-device init script.

SEE ALSO
bluetoothctl(1), python3-meshcore(3)

AUTHORS
meshcore-cli was written by the MeshCore developers.

This manual page was written for the Debian project by Patrick Winnertz <winnie@debian.org>.