WEBSOCAT(1)

🌸 NAME 🌸

okay bestie, welcome to the websocat(1) page from the User Commands manual — and the name is literally websocat — websocat 💅 yes, she said the same word twice, we move.

✨ DESCRIPTION ✨

This is websocat 1.14.1 by Vitaly "_Vi" Shukela <vi0oss@gmail.com> — a command-line client for web sockets, like netcat/curl/socat for ws://. No cap, that's the whole vibe 🫶.

🧚 USAGE 🧚

• simple client:

websocat ws://URL | wss://URL

(simple client)

• simple server:

websocat -s port

(simple server)

• advanced mode:

websocat [FLAGS] [OPTIONS] <addr1> <addr2>

(advanced mode)

💅 FLAGS 💅

some flags are hidden, see --help=long — yes bestie, there are hidden ones, don't @ me 🙈.

• -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 — this is not a drill.
• -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 []. cute.
• -0, --null-terminated — use \0 instead of \n for linemode. Also: --no-fixups to discover what is being inserted automatically and read the full manual about Websocat internal workings. (Yes, that's the exact note, bestie.)
• -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). They are different girls.
• --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 <auto_socks5> — use specified address:port as a SOCKS5 proxy. Example: --socks5 127.0.0.1:9050.
• --basic-auth <basic_auth> — add Authorization: Basic HTTP request header with this base64-encoded parameter. Also available as WEBSOCAT_BASIC_AUTH environment variable.
• --basic-auth-file <basic_auth_file> — add Authorization: Basic HTTP request header base64-encoded content of the specified file.
• -B, --buffer-size <buffer_size> — maximum message size, in bytes [default: 65536].
• --close-reason <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_status_code> — close connection with a status code.
• -H, --header <custom_headers>... — 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 <custom_reply_headers>... — 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 <headers_to_env>... — forward specified incoming request header to H_* environment variable for exec:-like specifiers.
• -h, --help <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 <max_messages> — maximum number of messages to copy in one direction.
• --max-messages-rev <max_messages_rev> — maximum number of messages to copy in the other direction.
• --conncap <max_parallel_conns> — maximum number of simultaneous connections for listening mode.
• --origin <origin> — add Origin HTTP header to websocket client request.
• --pkcs12-der <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 <pkcs12_passwd> — password for --pkcs12-der pkcs12 archive. Required on Mac.
• -p, --preamble <preamble>... — prepend copied data with a specified string. Can be specified multiple times.
• -P, --preamble-reverse <preamble_reverse>... — prepend copied data with a specified string (reverse direction). Can be specified multiple times.
• --restrict-uri <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_static_files>... — serve a named static file for non-websocket connections. Argument syntax: <URI>:<Content-Type>:<file-path>. 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 <useragent> — set User-Agent request header to this value. Similar to setting it with -H.
• --protocol <websocket_protocol> — specify this Sec-WebSocket-Protocol: header when connecting.
• --server-protocol <websocket_reply_protocol> — force this Sec-WebSocket-Protocol: header when accepting a connection.
• --websocket-version <websocket_version> — override the Sec-WebSocket-Version value.
• --ping-interval <ws_ping_interval> — send WebSocket pings each this number of seconds.
• --ping-timeout <ws_ping_timeout> — drop WebSocket connection if Pong message not received for this number of seconds.

🦋 ARGS 🦋

• <addr1> — 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.
• <addr2> — 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.

---

okay that's the whole page, bestie 💖 — footer vibes: websocat 1.14.1, date July 2026, manual name WEBSOCAT(1). Go be the main character of your socket connection 🫶✨