websocat: Usage, Options & Common CI Errors

websocat opens WebSocket connections from the shell, like netcat for ws/wss.

websocat is how pipelines smoke-test WebSocket endpoints. The CI hazard is that it stays connected forever by default, so a check hangs unless you use one-shot mode.

What it does

websocat connects to ws:// or wss:// URLs, sends stdin as messages, and prints received frames to stdout. It bridges WebSockets to stdio (and other transports), making it the netcat of the WebSocket world.

Common usage

Terminal

echo "ping" | websocat ws://localhost:8080/ws
websocat -1 ws://localhost:8080/ws            # one message then exit
echo '{"op":"ping"}' | websocat -n1 wss://host/ws
websocat --text ws://host/ws                   # treat frames as text
websocat -E ws://host/ws                        # exit on EOF

Options

Flag	What it does
-1 / --one-message	Send one message, receive one reply, exit
-n / --no-close	Do not send a close frame on EOF
--text / --binary	Force text or binary frame mode
-E / --exit-on-eof	Close the socket when stdin reaches EOF
-H "k: v"	Add a header to the opening handshake
-k / --insecure	Skip TLS certificate verification (wss)

Common errors in CI

websocat: WebSocketError: WebSocketError: Received unexpected status code (200 OK) - the server did not upgrade the connection (HTTP 101 expected); the path is wrong or it is not a WebSocket endpoint. "Connection refused" means nothing is listening. Without -1/-E the process never exits and hangs the job - always bound it (websocat -1 or wrap in timeout). For wss with self-signed certs you need -k. A 401/403 during the handshake usually means a missing auth header (-H).