zenoh-cli

Modern command-line interface for Zenoh distributed pub/sub and key-value storage

🚀 v0.2.0 Beta: Now with ROS2 support and pre-generated types for out-of-the-box pub/sub (no ROS2 installation required for common types)!

Quick Links:

• 🍎 Getting Started on macOS - Step-by-step Mac testing guide
• 🖥️ Platform Support Matrix - Officially supported OS/Node.js versions
• 📣 Beta Announcement - What's new and how to provide feedback

zenoh-cli is a developer-friendly CLI for Zenoh, inspired by mosquitto_pub/sub for MQTT. Perfect for:

• 🤖 Robotics - Debug ROS2/Zenoh bridges, sniff robot communication
• 🧪 Testing - Quick pub/sub testing without writing code
• 🔍 Development - Inspect Zenoh traffic in real-time
• 📚 Learning - Explore Zenoh features interactively

🧠 Design Philosophy

zenoh-cli follows the SchemaWhisperer pattern of intelligent auto-discovery with graceful degradation:

1. Discover Reality: Use Zenoh liveliness to find what's actually there (topics, types, publishers)
2. Infer Intent: Auto-detect message types and serialization formats (CDR vs JSON)
3. Detect Failure Modes: Handle key mangling, type mismatches, and network issues
4. Show Uncertainty: Display confidence scores and detection results
5. Execute with Guardrails: Safe deserialization, type validation, error recovery

This approach is inspired by the Guardian Protocol's distributed consciousness pattern and NexusFleet's SchemaWhisperer advanced mode - systems designed to handle chaos intelligently without requiring users to understand every implementation detail.

Key Principle: The tool should be smarter than the protocol's complexity.

Why This Matters

Zenoh's key expressions can be a mess (especially with ros2-zenoh mangling):

• /rt/robot_A1/sensors/lidar vs /robot_A1/sensors/lidar
• DDS type names like geometry_msgs::msg::dds_::Twist_
• CDR binary vs JSON serialization auto-switching

Instead of making you handle this, zenoh-cli discovers the actual structure, infers types via liveliness, and presents a clean interface. You focus on what you want to do, not how Zenoh/ROS2 represents it internally.

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g zenoh-cli

# Or use npx (no install needed)
npx zenoh-cli --help

Prerequisites

• Node.js 18+ (for native ESM support)
• Zenoh router (optional but recommended):

  # macOS (via Homebrew)
  brew install zenoh
  
  # Or download from https://zenoh.io/download

📖 Usage

Discovery

Discover Zenoh routers and peers on your network:

zenoh scout

# With timeout
zenoh scout --timeout 5000

# JSON output
zenoh scout --json

Publish

Publish data to a key expression:

# Simple publish
zenoh pub robot/cmd_vel '{"linear": 0.5, "angular": 0.0}'

# Publish from file
zenoh pub robot/config --file config.json

# Repeat publication
zenoh pub robot/heartbeat "alive" --repeat 10 --interval 1000

# Quiet mode (no output)
zenoh pub robot/data "..." --quiet

Subscribe

Subscribe to a key expression and print received data:

# Simple subscribe
zenoh sub robot/odom

# Wildcard subscription
zenoh sub 'robot/**'

# Limit message count
zenoh sub robot/scan --count 10

# JSON output (one per line)
zenoh sub robot/telemetry --json

# Verbose mode (show timestamps)
zenoh sub robot/data --verbose

# Quiet mode (values only)
zenoh sub robot/data --quiet

Query (Get)

Query data from Zenoh storage or queryables:

# Query a key
zenoh get robot/config

# Query with wildcard
zenoh get 'robot/params/**'

# Custom timeout
zenoh get robot/status --timeout 10000

# JSON output
zenoh get robot/config --json

Store (Put)

Store data in Zenoh key-value storage:

# Store a value
zenoh put robot/config '{"max_speed": 2.0}'

# Store from file
zenoh put robot/waypoints --file waypoints.json

# Quiet mode
zenoh put robot/data "..." --quiet

🎯 Real-World Examples

ROS2 Bridge Debugging

# Terminal 1: Start your ROS2/Zenoh bridge
ros2 run zenoh_bridge_dds zenoh_bridge_dds

# Terminal 2: Monitor all ROS2 topics via Zenoh
zenoh-cli sub 'rt/**' --verbose

# Terminal 3: Publish to a ROS2 topic via Zenoh
zenoh-cli pub rt/cmd_vel '{"linear": {"x": 0.5}}'

Robot Fleet Monitoring

# Subscribe to all robots' telemetry
zenoh sub 'fleet/*/telemetry' --json | jq .

# Publish command to specific robot
zenoh pub fleet/robot1/cmd '{"action": "goto", "x": 10, "y": 20}'

# Query all robot configurations
zenoh get 'fleet/*/config' --verbose

IoT Data Collection

# Monitor sensor data with timestamps
zenoh sub 'sensors/**' --verbose

# Store configuration
zenoh put device/sensor1/config '{"interval": 1000, "precision": 0.01}'

# Query sensor readings
zenoh get 'sensors/temperature/**'

🔧 Advanced Usage

Custom Zenoh Router

By default, zenoh connects to tcp/localhost:7447. To use a custom router:

# Set environment variable
export ZENOH_ROUTER=tcp/192.168.1.100:7447

# Or edit ~/.zenoh/config.json

Scripting

zenoh is designed for scripting:

#!/bin/bash
# Monitor robot and save to file
zenoh sub 'robot/odom' --json --count 100 > odom_data.jsonl

# Process with jq
cat odom_data.jsonl | jq -r '.value' | ...

Integration with Other Tools

# Pipe to jq for JSON processing
zenoh sub robot/telemetry --json | jq '.value | fromjson'

# Use in watch loop
watch -n 1 "zenoh get robot/status --json | jq ."

# Combine with mosquitto for MQTT bridge
zenoh sub 'zenoh/#' | while read msg; do mosquitto_pub -t mqtt/zenoh -m "$msg"; done

🏗️ Architecture

zenoh-cli is a thin wrapper around zenoh-ts, providing:

• ✅ Intuitive CLI (like mosquitto_pub/sub)
• ✅ Beautiful terminal output (colors, formatting)
• ✅ JSON output mode (for scripting)
• ✅ Tab completion (coming soon)
• ✅ Cross-platform (macOS, Linux, Windows)

🤝 Contributing

Contributions welcome! This project aims to fill the gap in Zenoh's tooling ecosystem.

# Clone the repo
git clone https://github.com/balans-collective/zenoh-cli.git
cd zenoh-cli

# Install dependencies
npm install

# Build
npm run build

# Test
npm start -- sub 'test/**'

📚 Resources

• Zenoh Documentation
• Zenoh GitHub
• ROS2 Zenoh Bridge
• Dyno Robotics

📄 License

MIT © 2025 Samuel Lindgren / Balans Collective

🙏 Acknowledgments

• Eclipse Zenoh team for the amazing protocol
• mosquitto_pub/sub for CLI inspiration

Made with ❤️ for the robotics and distributed systems community