WEBSOCAT(1) User Commands WEBSOCAT(1) NAME websocat - websocat DESCRIPTION websocat 1.14.1 Vitaly "_Vi" Shukela Command-line client for web sockets, like netcat/curl/socat for ws://. USAGE: websocat ws://URL | wss://URL (simple client) websocat -s port (simple server) websocat [FLAGS] [OPTIONS] (advanced mode) FLAGS: (some flags are hidden, see --help=long) -e, --set-environment Set WEBSOCAT_* environment variables when doing exec:/cmd:/sh-c: Currently it's WEBSOCAT_URI and WEBSOCAT_CLIENT for request URI and client address (if TCP) Beware of ShellShock or similar security problems. -E, --exit-on-eof Close a data transfer direction if the other one reached EOF --jsonrpc Format messages you type as JSON RPC 2.0 method calls. First word becomes method name, the rest becomes parameters, possibly automatically wrapped in []. -0, --null-terminated Use \0 instead of \n for linemode --no-fixups to discover what is being inserted automatically and read the full manual about Websocat internal workings. -1, --one-message Send and/or receive only one message. Use with --no-close and/or -u/-U. --oneshot Serve only once. Not to be confused with -1 (--one-message) --print-ping-rtts Print measured round-trip-time to stderr after each received WebSocket pong. -q Suppress all diagnostic messages, except of startup errors -s, --server-mode Simple server mode: specify TCP port or addr:port as single argument -S, --strict strict line/message mode: drop too long messages instead of splitting them, drop incomplete lines. -k, --insecure Accept invalid certificates and hostnames while connecting to TLS -u, --unidirectional Inhibit copying data in one direction -U, --unidirectional-reverse Inhibit copying data in the other direction (or maybe in both directions if combined with -u) -v Increase verbosity level to info or further -b, --binary Send message to WebSockets as binary messages -n, --no-close Don't send Close message to websocket on EOF -t, --text Send message to WebSockets as text messages --base64 Encode incoming binary WebSocket messages in one-line Base64 If `--binary-prefix` (see `--help=full`) is set, outgoing WebSocket messages that start with the prefix are decoded from base64 prior to sending. OPTIONS: (some options are hidden, see --help=long) --socks5 Use specified address:port as a SOCKS5 proxy. Example: --socks5 127.0.0.1:9050 --basic-auth Add `Authorization: Basic` HTTP request header with this base64-encoded parameter. Also available as `WEBSOCAT_BASIC_AUTH` environment variable --basic-auth-file Add `Authorization: Basic` HTTP request header base64-encoded content of the specified file -B, --buffer-size Maximum message size, in bytes [default: 65536] --close-reason Close connection with a reason message. This option only takes effect if --close-status-code option is provided as well. --close-status-code Close connection with a status code. -H, --header ... Add custom HTTP header to websocket client request. Separate header name and value with a colon and optionally a single space. Can be used multiple times. Note that single -H may eat multiple further arguments, leading to confusing errors. Specify headers at the end or with equal sign like -H='X: y'. --server-header ... Add custom HTTP header to websocket upgrade reply. Separate header name and value with a colon and optionally a single space. Can be used multiple times. Note that single -H may eat multiple further arguments, leading to confusing errors. --header-to-env ... Forward specified incoming request header to H_* environment variable for `exec:`-like specifiers. -h, --help See the help. --help=short is the list of easy options and address types --help=long lists all options and types (see [A] markers) --help=doc also shows longer description and examples. --max-messages Maximum number of messages to copy in one direction. --max-messages-rev Maximum number of messages to copy in the other direction. --conncap Maximum number of simultaneous connections for listening mode --origin Add Origin HTTP header to websocket client request --pkcs12-der Pkcs12 archive needed to accept SSL connections, certificate and key. A command to output it: openssl pkcs12 -export -out output.pkcs12 -inkey key.pem -in cert.pem Use with -s (--server-mode) option or with manually specified TLS overlays. See moreexamples.md for more info. --pkcs12-passwd Password for --pkcs12-der pkcs12 archive. Required on Mac. -p, --preamble ... Prepend copied data with a specified string. Can be specified multiple times. -P, --preamble-reverse ... Prepend copied data with a specified string (reverse direction). Can be specified multiple times. --restrict-uri When serving a websocket, only accept the given URI, like `/ws` This liberates other URIs for things like serving static files or proxying. -F, --static-file ... Serve a named static file for non-websocket connections. Argument syntax: :: Argument example: /index.html:text/html:index.html Directories are not and will not be supported for security reasons. Can be specified multiple times. Recommended to specify them at the end or with equal sign like `-F=...`, otherwise this option may eat positional arguments --ua Set `User-Agent` request header to this value. Similar to setting it with `-H`. --protocol Specify this Sec-WebSocket-Protocol: header when connecting --server-protocol Force this Sec-WebSocket-Protocol: header when accepting a connection --websocket-version Override the Sec-WebSocket-Version value --ping-interval Send WebSocket pings each this number of seconds --ping-timeout Drop WebSocket connection if Pong message not received for this number of seconds ARGS: In simple mode, WebSocket URL to connect. In advanced mode first address (there are many kinds of addresses) to use. See --help=types for info about address types. If this is an address for listening, it will try serving multiple connections. In advanced mode, second address to connect. If this is an address for listening, it will accept only one connection. Basic examples: Command-line websocket client: websocat ws://ws.vi-server.org/mirror/ WebSocket server websocat -s 8080 WebSocket-to-TCP proxy: websocat --binary ws-l:127.0.0.1:8080 tcp:127.0.0.1:5678 Partial list of address types: ws:// Insecure (ws://) WebSocket client. Argument is host and URL. wss:// Secure (wss://) WebSocket client. Argument is host and URL. ws-listen: WebSocket server. Argument is host and port to listen. wss-listen: Listen for secure WebSocket connections on a TCP port tcp: Connect to specified TCP host and port. Argument is a socket address. tcp-listen: Listen TCP port on specified address. ssl-listen: Listen for SSL connections on a TCP port sh-c: Start specified command line using `sh -c` (even on Windows) cmd: Start specified command line using `sh -c` or `cmd /C` (depending on platform) readfile: Synchronously read a file. Argument is a file path. writefile: Synchronously truncate and write a file. appendfile: Synchronously append a file. udp: Send and receive packets to specified UDP socket, from random UDP port udp-listen: Bind an UDP socket to specified host:port, receive packet - Read input from console, print to console. Uses threaded implementation even on UNIX unless requested by `--async-stdio` CLI option. mirror: Simply copy output to input. No arguments needed. literalreply: Reply with a specified string for each input packet. literal: Output a string, discard input. random: Generate random bytes when being read from, discard written bytes. Partial list of overlays: broadcast: Reuse this connection for serving multiple clients, sending replies to all clients. autoreconnect: Re-establish underlying connection on any error or EOF foreachmsg: Execute something for each incoming message. log: Log each buffer as it pass though the underlying connector. See more address types with the --help=long option. See short examples and --dump-spec names for most address types and overlays with --help=doc option websocat 1.14.1 July 2026 WEBSOCAT(1)