MESHCORE-CLI(1)

📦 version 1.5.7, in ubuntu stonking

🦋 MESHCORE-CLI(1) 🦋

okay bestie, listen — this is the manual for meshcore-cli, living in section 1 of the Amateur Radio manual. Its other name is meshcli, and it's literally the same thing, so don't @ me. 💅

✨ NAME ✨

meshcore-cli — the CLI interface to the MeshCore companion app over BLE, TCP or Serial. 🫶

🌸 SYNOPSIS 🌸

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

💖 DESCRIPTION 💖

meshcore-cli (you can also call it meshcli, they're the same girl) connects to a MeshCore companion radio node over BLE, TCP or serial, and lets you vibe with it from your terminal through a command line interface. no cap. 🎀

You can yeet commands in as arguments on the command line (perfect for scripting or one-shot use), or just type them in interactively when you don't pass any command at all. When you're in interactive mode (aka chat mode) you can pick a contact — another client, a repeater, a sensor or a room — and interact with it. For clients that means sending and receiving messages; for repeaters, rooms and sensors you get the remote CLI directly (tho you can still send messages to rooms using the msg command or a double-quote prefix 💌).

There's also a dedicated serial repeater mode, and you turn it on with -r. It connects straight to repeater hardware over UART, and it adds line editing, history, completion, clock sync and region file transfer. iconic behaviour, honestly. 👑

⚠️ heads up bestie: most MeshCore companion nodes are compiled with only one transport interface (BLE, serial, or TCP), so you must use the matching connection option. pick wrong and she simply will not answer. 💀

🌈 OPTIONS 🌈

  • -h — Print help and exit. 🆘
  • -v — Print version and exit. ⭐
  • -j — JSON output mode. Also disables init file execution (so your init file gets benched for this run).
  • -D — Enable debug output. 🐛 we love a diagnostic queen.
  • -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 the 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, and 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 go after the options on the command line, and yes, you can chain them like a little braid. 🧚 Many commands have short aliases. Prefix a command with . (a dot) to force JSON output for that command, no matter what the global -j flag says — it's giving main character energy. ✨ And if you need extra help on a specific command, use ?cmd.

🌸 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 your own telemetry. 📊
  • card (alias: e) — Export this node's URI.
  • ver (alias: v) — Show firmware version. ⭐
  • reboot — Reboot the node. 🔄 bye bestie 4 a sec
  • 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 number channel.
  • 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 the available parameters.
  • set param value — Set a parameter value. Use set help for the 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 commands below send MeshCore protocol messages to a repeater via the companion node (that's 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 — she will not confirm, she's mysterious like that 💅).
  • 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 just kinda happens automatically when you don't give a command. ✨ It gives you a prompt with the node name, plus command history and tab completion — so fancy.

The to command picks the recipient for everything you do next:

  • 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're inside a chat node, the default action is just send messages. Inside a repeater or room server, your input gets forwarded as commands instead. Wanna send a message to a room anyway? Prefix it with " (double-quote) or use the msg command. 💬

The / character bypasses whatever node is currently selected:

  • /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. The moment you enter interactive mode, the scope gets reset to * (that's classic flood). Want to change it? Use the scope command, or postfix the to command with %scope. You can also slap a scope on a single command by prepending %scope — e.g. login%#Morbihan. 🗺️

📢 Channel Echoes 📢

When you enable it with /set channel_echoes on, all channel messages get 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. fr fr, it's giving full receipts. 💖

📡 REPEATER COMMANDS 💅

okay bestie so here's the tea: meshcore-cli can slide into a repeater through two completely different paths. Two doors, same house, very versatile of it fr fr.

🔌 Serial Direct Mode (-r -s port)

This one plugs the USB straight into the repeater hardware. The CLI talks to the firmware's text CLI over UART. No mesh, no radio, just vibes through a cable. 🪢

🦋 Client Mode (to <repeater>)

Here you connect to the companion node first — BLE, TCP, or serial without -r — and then you send commands across the mesh radio using encrypted MeshCore cmd messages. Spicy, indirect, iconic. 💌

🫶 Commands Available in Both Modes

  • ver, board, clock — the information commands. Just asking the node "who are you, what are you running, what time is it" 🕐
  • stats-core, stats-radio, stats-packets, clear stats — statistics, babes. Numbers about how it's doing. 📊
  • neighbors, neighbor.remove n, discover.neighbors, advert — network management, aka the social life of the mesh. 👯
  • log start / log stop — turn packet logging on or off. Heads up: in client mode, log data comes back as RX_LOG_DATA events with rich packet parsing (gorgeous). In serial mode it's just printed as raw firmware text. Same switch, different energy. ✨
  • get param / set param value — get or set configuration parameters. The full param list is: 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. That's a long list, memorize at your own pace. 📝
  • region [sub-command] — region management. Sub-commands: save, home, get, put, remove, allowf, denyf. 🗺️
  • gps on|off, gps sync, gps setloc, gps advert none|share|prefs — all the GPS control bestie 🛰️
  • sensor list / sensor get / sensor set — sensor management. 🔬
  • password pwd, powersaving on|off, setperm keyperm
  • time epoch, reboot, erase — miscellaneous commands. A little grab bag, a little sampler platter. 🍓

🧚 Serial-Only Commands (-r)

These only work when you're hardwired in, bestie. Cable energy only. 🔌

  • log — dump the stored log file to the console.
  • log erase — yeet 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. Temporary, like everything. 🫠
  • script file — execute a local script file (lines get sent one by one over serial).
  • clock sync — sync the repeater clock to the host time. Slight drama here: meshcore-cli intercepts this one and sends time epoch to the firmware instead. 🕰️

👑 Client-Mode-Only Commands

Radio-route exclusives, no cable required, so slay. 📻

  • login pwd (alias: l) — log into the repeater. 🔑
  • logout — log out of the repeater. bye bestie 👋
  • req_status (alias: rs), req_neighbours (alias: rn)
  • req_regions (alias: rr), req_owner (alias: ro)
  • req_clock, req_acl (alias: ra) — these are all binary protocol requests.
  • trace (alias: tr), dtrace (alias: dt) — path tracing via the mesh. Following the breadcrumbs 🍞
  • 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 something 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

This sends commands to all contacts matching filter. And the filter? It's a comma-separated list of conditions. Let's go through them one by one:

  • u<timestamp or u>timestamp — match by modification time relative to a timestamp. You can 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. And when you're writing them from the command line, use commas to delimit filter fields clearly — that's how it knows where one field ends and the next begins. ✨

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

⚙️ CONFIGURATION

Configuration files live in $HOME/.config/meshcore. 🏠

If that directory exists, the default BLE address and your command history get stored there. Cute little memory box.

If a file named init exists in this directory, it's executed automatically — right before any commands given on the command line, and after option parsing. Sneaky but useful.

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

💖 EXAMPLES

okay this is the fun part, bestie. copy these and go.

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/ — the configuration directory. It's 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. legends, honestly.

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

aaaand that's the whole page bestie!! this was meshcore-cli version 1.5.7, dated 2026-05-02. now go forth and slay some repeaters 💅✨🦋

📦 where this page comes from