How to Install and Use websocat in Linux for Interactive WebSocket Client Connection Testing and Debugging

For standard HTTP and REST APIs, Linux developers have a rich arsenal of command-line tools such as curl, wget, and httpie. However, when debugging full-duplex, bi-directional persistent protocols like WebSockets (ws:// and wss://)—used universally in real-time chat applications, cryptocurrency trading feeds, IoT telemetry, and live streaming services—standard HTTP clients cannot maintain persistent socket sessions.

websocat is an open-source command-line utility built in Rust that functions as a netcat (nc) or socat for WebSockets. It allows developers to connect to WebSocket endpoints, transmit text and binary JSON payloads interactively, forward standard UNIX pipes across sockets, and even establish local mock WebSocket listener servers. This guide details how to install, connect, and debug WebSockets using websocat.

Installing websocat on Linux

Method 1: Download Pre-Compiled Binary (Fastest)

# Download latest release from GitHub
curl -s https://api.github.com/repos/vi/websocat/releases/latest \
  | grep "browser_download_url.*linux-x86_64" \
  | cut -d : -f 2,3 \
  | tr -d \" \
  | wget -qi -

# Rename, make executable, and move to PATH
chmod +x websocat.x86_64-unknown-linux-musl
sudo mv websocat.x86_64-unknown-linux-musl /usr/local/bin/websocat

Method 2: Install via Cargo

cargo install websocat

Interactive WebSocket Testing Workflows

1. Connecting to a Public WebSocket Echo Server

To initiate an interactive terminal session where lines typed into the console are transmitted directly over the WebSocket:

websocat wss://echo.websocket.events

Once connected, every string or JSON message you type is transmitted to the server and echoed back to standard output in real time.

2. Transmitting File Payloads and Closing Gracefully

Pipe a JSON configuration payload into an authenticated WebSocket endpoint:

cat payload.json | websocat -n1 wss://api.example.com/v1/subscribe

The -n1 flag instructs websocat to disconnect cleanly after transmitting the single message.

3. Spawning a Local WebSocket Listener Server

When developing frontend web applications before the backend API is ready, spawn a lightweight WebSocket server on port 8080:

websocat -s 8080

Any message sent by connecting web browsers will be displayed directly in your Linux terminal.

Key websocat Flags Reference Table

Flag	Function	Recommended Context
-s, --server	Listens as WebSocket server	Mock testing frontend applications
-k, --insecure	Skips TLS certificate validation	Testing self-signed local dev certificates
-t, --text	Forces text frame encoding	Preventing binary framing issues
--ping-interval N	Sends ping keep-alive every N seconds	Preventing proxy timeout disconnections
-H "Header: Val"	Passes custom HTTP handshake headers	Authentication tokens and Bearer headers