--- name: "websocat" section: "1" platform: "linux" package: "websocat" version: "1.14.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/websocat" --- # websocat(1) websocat ## 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