README

websocat
Netcat, curl and socat for WebSockets.




 Examples

 Connect to public echo server (Ctrl+d to quit)


$ websocat ws://ws.vi-server.org/mirror
123
123
ABC
ABC

$ docker run --rm -ti ghcr.io/vi/websocat:nightly wss://ws.vi-server.org/mirror
123
123
ABC
ABC


 Serve and connect


A$ websocat -s 1234
Listening on ws://127.0.0.1:1234/
ABC
123

B$ websocat ws://127.0.0.1:1234/
ABC
123


 Open a tab in Chromium using remote debugging.


$ chromium --remote-debugging-port=9222&
$ curl -sg http://127.0.0.1:9222/json/new | grep webSocketDebuggerUrl | cut -d'"' -f4 | head -1
ws://127.0.0.1:9222/devtools/page/A331E56CCB8615EB4FCB720425A82259
$ echo 'Page.navigate {"url":"https://example.com"}' | websocat -n1 --jsonrpc --jsonrpc-omit-jsonrpc ws://127.0.0.1:9222/devtools/page/A331E56CCB8615EB4FCB720425A82259
{"id":2,"result":{"frameId":"A331E56CCB8615EB4FCB720425A82259","loaderId":"EF5AAD19F2F8BB27FAF55F94FFB27DF9"}}



 Proxy TCP connections to WebSocket connections and back.


$ websocat --oneshot -b ws-l:127.0.0.1:1234 tcp:127.0.0.1:22&
$ websocat --oneshot -b tcp-l:127.0.0.1:1236 ws://127.0.0.1:1234/&
$ nc 127.0.0.1 1236
SSH-2.0-OpenSSH_7.4p1 Debian-10+deb9u3
qwertyu
Protocol mismatch.



 Broadcast all messages between connected WebSocket clients


A$ websocat -t ws-l:127.0.0.1:1234 broadcast:mirror:
B$ websocat ws://127.0.0.1:1234
C$ websocat ws://127.0.0.1:1234


(if you like this one, you may actually want https://github.com/vi/wsbroad/ instead)

See moreexamples.md for further examples.

 Features

 Connecting to and serving WebSockets from command line.
 Executing external program and making it communicate to WebSocket using stdin/stdout.
 Text and binary modes, converting between lines (or null-terminated records) and messages.
 Inetd mode, UNIX sockets (including abstract namespaced on Linux).
 Integration with Nginx using TCP or UNIX sockets.
 Directly using unauthenticated SOCKS5 servers for connecting to WebSockets and listening WebSocket connection.
 Auto-reconnect and connection-reuse modes.
 Linux, Windows and Mac support, with [pre-built executables][releases].
 Low-level WebSocket clients and servers with overridable underlying transport connection, e.g. calling external program to serve as a transport for websocat (for SSL, proxying, etc.).

[releases]:https://github.com/vi/websocat/releases

 Installation

There are multiple options for installing WebSocat. From easy to hard:

 FreeBSD

pkg install websocat

 Debian / Ubuntu
 Download a pre-build executable from [GitHub releases][releases].
 Websocat is not yet officially packaged for Debian. Some older versions of Websocat may also have Debian package files available on Github releases.

 macOS

Homebrew: brew install websocat

MacPorts: sudo port install websocat

 From source
 Install the Rust toolchain and do cargo install websocat. If something fails with a -sys crate, try with --no-default-features;
 Build Websocat from source code (see below), then move target/release/we