https://github.com/statico/meshtastic-cli
🌌 Terminal UI for monitoring Meshtastic mesh networks - view packets, nodes, and chat in real-time
https://github.com/statico/meshtastic-cli
bun claude cli ink lora mesh-network meshtastic meshtastic-addon monitoring react terminal tui vibe-coded vibe-coding
Last synced: 1 day ago
JSON representation
🌌 Terminal UI for monitoring Meshtastic mesh networks - view packets, nodes, and chat in real-time
- Host: GitHub
- URL: https://github.com/statico/meshtastic-cli
- Owner: statico
- License: mit
- Created: 2025-12-18T16:40:39.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-01-12T06:05:13.000Z (6 days ago)
- Last Synced: 2026-01-13T22:54:07.996Z (4 days ago)
- Topics: bun, claude, cli, ink, lora, mesh-network, meshtastic, meshtastic-addon, monitoring, react, terminal, tui, vibe-coded, vibe-coding
- Language: TypeScript
- Homepage:
- Size: 636 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Meshtastic CLI
[](https://github.com/statico/meshtastic-cli/actions/workflows/build.yml)
[](https://github.com/statico/meshtastic-cli/actions/workflows/docker.yml)
[](https://github.com/statico/meshtastic-cli/releases)
[](LICENSE)
Live Packet View
Node List
Chat Channels
Interactive Help
\
> [!WARNING]
> This project was completely vibe-coded with [Claude Code](https://claude.com/claude-code) and [Cursor](https://www.cursor.com/).
A terminal UI for monitoring and configuring Meshtastic mesh networks. Connects to a Meshtastic node via HTTP and displays real-time packet traffic, node information, chat messages, and device configuration.
## Features
- **Packets view** - Live packet stream with detailed inspection (decoded payload, JSON, hex dump)
- **Nodes view** - Discovered nodes with signal quality, battery, position, hardware, favorites
- **Chat view** - Send and receive channel messages with emoji support and delivery status
- **DM view** - Direct messages with delivery status and resend support
- **Config view** - View and edit device configuration with batch mode
- **Log view** - Position, traceroute, and nodeinfo response history
- **Node commands** - Traceroute, position/telemetry/nodeinfo request, direct ping, DM
- **ACK notifications** - Visual feedback when nodes acknowledge your packets
- **MeshView integration** - Update node info from a MeshView server, view live MeshView traffic
- **Persistent storage** - SQLite database for nodes, messages, and packets
- **Session support** - Multiple named sessions for different radios
## Installation
### Download Binary
Grab the latest release for your platform from the [Releases page](../../releases).
```sh
chmod +x meshtastic-cli-darwin-arm64
./meshtastic-cli-darwin-arm64 192.168.1.100
```
Note: macOS binaries are not codesigned. You may need to right-click and select "Open" or run `xattr -d com.apple.quarantine ` to bypass Gatekeeper.
### Docker
```sh
docker volume create meshtastic-cli
docker run --rm -it -e TERM -v meshtastic-cli:/root/.config ghcr.io/statico/meshtastic-cli 192.168.1.100
# With MeshView integration (e.g., Baymesh)
docker run --rm -it -e TERM -v meshtastic-cli:/root/.config ghcr.io/statico/meshtastic-cli 192.168.1.100 --meshview https://meshview.bayme.sh
```
### Build from Source
Requires [Bun](https://bun.sh).
```sh
bun install
bun run dev 192.168.1.100
```
## Usage
```
meshtastic-cli
[options]
Arguments:
address Device address (required) - IP address, hostname, or serial port
Options:
--session, -s Session name for database (default: default)
--clear Clear the database for the session and exit
--skip-config Skip loading device configuration on startup
--skip-nodes Skip downloading node database (faster connect)
--meshview, -m MeshView URL for packet/node links
--fahrenheit, -F Display temperatures in Fahrenheit
--port, -P HTTP port number (default: 4403 if no port in address)
--tls, -T Use HTTPS instead of HTTP
--insecure, -k Accept self-signed SSL certificates
--help, -h Show help
```
### Examples
Connect to a Meshtastic device (default port 4403):
```sh
meshtastic-cli 192.168.0.123
```
Connect to meshtasticd HTTP API (port 8080 with HTTPS):
```sh
meshtastic-cli 127.0.0.1 --port 8080 --tls --insecure
```
> **Note:** meshtasticd servers need to have the webserver enabled. The webserver typically runs on port 8080 with HTTPS. Check your meshtasticd configuration to ensure the webserver is enabled.
Connect to a device on a custom port:
```sh
meshtastic-cli 192.168.1.100 --port 8080
```
Connect with HTTPS and accept self-signed certificate:
```sh
meshtastic-cli example.com --tls --insecure
```
## Message Status Indicators
In Chat and DM views, messages show delivery status:
| Indicator | Meaning |
|-----------|---------|
| `[...]` | Pending - waiting for acknowledgment |
| `[✓]` | Acknowledged - recipient confirmed receipt |
| `[✗]` | Failed - delivery failed or timed out |
| `[M]` | MeshView confirmed - packet seen on MeshView server |
The `[M]` indicator also appears in the Packets view when a MeshView URL is configured. This confirms the packet was received by the MeshView aggregation server, which is useful for verifying mesh propagation.
## Terminal Compatibility
For proper emoji and Unicode character display, ensure your terminal uses Unicode-compliant width calculations:
- **Ghostty** - Uses Unicode widths by default (`grapheme-width-method = unicode`)
- **Kitty** - Uses Unicode widths by default
- **iTerm2** - Enable in Preferences → Profiles → Text → "Unicode version 9+ widths"
- **Terminal.app** - May have issues with some emoji
There are still issues with some emoji and fixing them is a work in progress.
## Keybindings
### Global
| Key | Action |
|-----|--------|
| 1-7 | Switch to view (7 with MeshView) |
| [ / ] | Previous / Next view |
| Ctrl+L | Redraw screen |
| q | Quit |
| ? | Toggle help |
### Packets View
| Key | Action |
|-----|--------|
| j/k | Navigate packets |
| g/G | First/last packet |
| h/l | Switch inspector tab |
| Tab | Toggle pane sizes |
| +/- | Resize inspector |
| m | Open position in Maps |
| n/Enter | Jump to sender node |
| u | Update node from MeshView |
| o | Open packet in MeshView |
### Nodes View
| Key | Action |
|-----|--------|
| j/k | Navigate nodes |
| / | Filter nodes |
| t | Traceroute |
| p | Request position |
| e | Request telemetry |
| d | Start DM |
| D | Direct ping (hop=0) |
| u | Update from MeshView |
| U | Update all unknown from MeshView |
| m | Open position in Maps |
| l | Lookup hardware model |
| f | Toggle favorite |
| i | Request node info |
| I | Toggle ignored |
| x | Remove node from DB |
| H | Sort by hops |
| S | Sort by SNR |
| B | Sort by battery |
| A | Sort by age (last heard) |
| F | Sort by favorites |
### Chat View
| Key | Action |
|-----|--------|
| j/k | Navigate messages |
| / | Filter messages |
| Tab | Switch channel |
| n | Go to sender node |
| d | DM the sender |
| u | Update node from MeshView |
| R | Resend failed message |
| Enter | Focus input |
| Alt+E | Emoji selector |
| Escape | Unfocus / Exit |
### DM View
| Key | Action |
|-----|--------|
| j/k | Navigate conversations or messages |
| l/→ | Enter message selection mode |
| h/← | Back to conversation list |
| n | Go to node |
| u | Update node from MeshView |
| R | Resend failed message |
| Enter | Focus input |
| Escape | Back / Unfocus |
| # | Delete conversation |
### Log View
| Key | Action |
|-----|--------|
| j/k | Navigate responses |
| g/G | First/last response |
### Config View
| Key | Action |
|-----|--------|
| h/j/k/l | Navigate menu |
| Enter | Select section |
| j/k | Navigate config fields |
| g/G | First/last field |
| c | Commit changes |
| C | Discard changes |
| Escape | Back to menu |
| r | Reboot device |
### Channel Config
| Key | Action |
|-----|--------|
| j/k | Navigate channels |
| e | Edit channel name |
| r | Cycle channel role |
| p | Edit encryption key (PSK) |
| u | Toggle uplink |
| D | Toggle downlink |
## License
MIT