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