Skip to content

websocket.md

Latest commit

 

History

History
106 lines (71 loc) · 2.93 KB

websocket.md

File metadata and controls

106 lines (71 loc) · 2.93 KB

WebSocket

fetch supports WebSocket connections for real-time bidirectional communication.

Basic Usage

Connect using ws:// or wss:// URL schemes:

fetch ws://echo.websocket.events
fetch wss://echo.websocket.events

Sending Messages

Initial Message

Use -d or -j to send a single message on connect:

fetch ws://echo.websocket.events -d "hello"
fetch ws://echo.websocket.events -j '{"type": "subscribe", "channel": "updates"}'

Piped Input

Pipe lines from stdin — each line is sent as a separate text message:

echo "hello" | fetch ws://echo.websocket.events
printf "msg1\nmsg2\n" | fetch ws://echo.websocket.events

When stdin/stdout/stderr are terminals, fetch opens an interactive prompt. Type a message and press Enter to send it. Use Ctrl+C or Ctrl+D to exit.

Control this behavior with --ws-interactive:

# Automatically use the prompt when attached to a terminal
fetch ws://api.example.com/stream --ws-interactive auto

# Require the prompt, failing if stdio is not a terminal
fetch ws://api.example.com/stream --ws-interactive on

# Disable the prompt and stream server messages to stdout
fetch ws://api.example.com/stream --ws-interactive off

Output

  • Text messages: Written to stdout. JSON messages are automatically formatted when connected to a terminal.
  • Binary messages: A [binary N bytes] indicator is printed to stderr.
  • Formatting: Use --format on to force JSON formatting, or --format off to disable it.
# Force JSON formatting
fetch ws://api.example.com/stream --format on

# Disable formatting
fetch ws://api.example.com/stream --format off

Verbose Output

Use -v flags to see connection details:

# Show response status and headers
fetch -v ws://echo.websocket.events -d "hello"

# Show request and response headers with prefixes
fetch -vv ws://echo.websocket.events -d "hello"

Authentication

All authentication options work with WebSocket connections — headers are sent during the HTTP upgrade handshake:

fetch --bearer mytoken ws://api.example.com/ws
fetch --basic user:pass ws://api.example.com/ws
fetch -H "Authorization: Bearer mytoken" ws://api.example.com/ws

Subprotocols

Specify WebSocket subprotocols via the Sec-WebSocket-Protocol header:

fetch -H "Sec-WebSocket-Protocol: graphql-ws" wss://api.example.com/graphql

Timeout

The --timeout flag applies to the WebSocket handshake only. The connection stays open until the server closes or stdin EOF:

fetch --timeout 5 ws://api.example.com/ws

Limitations

  • WebSocket requires HTTP/1.1 for the upgrade handshake. Using --http 3 with WebSocket is not supported.
  • WebSocket (ws:// / wss://) cannot be combined with --grpc, --form, --multipart, --xml, --edit, output-file/clipboard flags, or retry flags.
  • Binary message content is not displayed; only a size indicator is shown.
  • The pager is disabled for WebSocket output.