websocat — Command-Line WebSocket Client Like Netcat

Introduction

websocat bridges the gap between traditional Unix command-line tools and WebSocket-based services. It provides a socat-like interface for bidirectional communication over WebSocket connections, making it straightforward to test, debug, and script interactions with WebSocket APIs.

What websocat Does

• Connects to WebSocket servers as a client or listens as a server
• Pipes data between stdin/stdout and WebSocket connections
• Supports TLS for secure wss:// connections
• Provides proxy and relay modes for bridging protocols
• Handles both text and binary WebSocket frames

Architecture Overview

websocat is built in Rust using the tokio async runtime and the tungstenite WebSocket library. It models connections as a pair of read/write halves, allowing flexible composition of data sources and sinks. The tool supports a specifier syntax that lets you chain connections, for example piping a TCP listener through a WebSocket connection to another endpoint.

Self-Hosting & Configuration

• Install via cargo install websocat or download prebuilt binaries
• No configuration file needed; all options are passed as command-line flags
• Use --binary flag for binary frame mode instead of text
• Set custom headers with -H "Header: value" for authentication
• Enable autoreconnect with --autoreconnect for resilient connections

Key Features

• Single static binary with no runtime dependencies
• Supports Unix sockets, TCP, UDP, and stdio as endpoints
• Built-in WebSocket server mode for quick prototyping
• Message-based and line-based framing modes
• Composable address specifiers for complex routing

Comparison with Similar Tools

• wscat — Node.js WebSocket client, simpler but requires a Node runtime
• curl — Supports WebSocket since v7.86 but with limited interactivity
• socat — General-purpose relay tool, no native WebSocket support
• webwrap — Lightweight WebSocket proxy, less feature-rich

FAQ

Q: Can websocat act as a WebSocket server? A: Yes. Use websocat -s 8080 to start a simple WebSocket server on port 8080.

Q: How do I send binary data? A: Use the --binary flag and pipe binary data through stdin. websocat will send it as binary WebSocket frames.

Q: Does it support authentication? A: Yes. Pass custom headers with -H flags, including Authorization headers for token-based auth.

Q: Can I use websocat for load testing? A: websocat is designed for single-connection debugging and scripting, not for high-concurrency load testing.

Sources

• https://github.com/vi/websocat
• https://github.com/vi/websocat/blob/master/doc.md