WebSocket
Open named WebSocket connections that stay open between calls, send and receive messages, ping and close them. Typical uses: talk to a real-time service, follow a stream of events.
ws connectws connectws sendws sendws receivews receivews receive_allws receive_allws pingws pingws showws showws closews closews close_all

ws connect <name> <url>


Description

    Open a connection under a name: JSON {name, url, state, subprotocol, tls_verified, connected_at, idle_s, queued, queued_bytes, paused, received, sent, pings, pongs, close_code, close_reason, error}. A name already open is refused

Parameters

    name:   The name of the connection (letters, digits, _ . -, 64 at most) - String - required
    url:   ws:// or wss:// address - String - required
admin
ws connect "chat" "ws://127.0.0.1:22001/echo"
mentdb
{"name": "chat", "url": "ws://127.0.0.1:22001/echo", "state": "open", "subprotocol": null, "tls_verified": null, "connected_at": "2026-11-05T05:41:24.027Z", "idle_s": 0, "queued": 0, "queued_bytes": 0, "paused": false, "received": 0, "sent": 0, "pings": 0, "pongs": 0, "close_code": null, "close_reason": null, "error": null}
Fixed result from a real call to a local test server (127.0.0.1): a self-signed certificate is refused by default
admin
ws connect "x" "wss://localhost:22002/echo"
mentdb
Sorry, an error appears (the WebSocket connection failed: tls: (certificate_unknown) PKIX path building failed: unable to find valid certification path to requested target).

ws connect <name> <url> <json_params>


Description

    Open a connection with parameters: bearer, headers (object), subprotocols (array), timeout_ms (10000), max_message_bytes, max_queue, max_queue_bytes, idle_timeout_s, ca_file, insecure, allow_http

Parameters

    name:   The name - String - required
    url:   The address - String - required
    json_params:   The parameters - String - required
admin
ws connect "feed" "ws://127.0.0.1:22001/headers" "{\"bearer\": \"tok-abc123\", \"headers\": {\"X-Test\": \"v1\"}, \"subprotocols\": [\"chat.v2\"], \"timeout_ms\": 5000, \"max_queue\": 100}"
mentdb
{"name": "feed", "url": "ws://127.0.0.1:22001/headers", "state": "open", "subprotocol": "chat.v2", "tls_verified": null, "connected_at": "2026-11-05T05:41:24.548Z", "idle_s": 0, "queued": 1, "queued_bytes": 58, "paused": false, "received": 1, "sent": 0, "pings": 0, "pongs": 0, "close_code": null, "close_reason": null, "error": null}
Fixed result from a real call to a local test server (127.0.0.1): what the server received
admin
ws receive "feed"
mentdb
{"received": true, "type": "text", "data": "{\"auth\": \"Bearer tok-abc123\", \"x\": \"v1\", \"sub\": \"chat.v2\"}", "bytes": 58}

ws send <name> <data>


Description

    Send a text message: JSON {sent, bytes}

Parameters

    name:   The connection - String - required
    data:   The text, 16 MB at most - String - required
admin
ws send "chat" "hello"
mentdb
{"sent": true, "bytes": 5}

ws send <name> <data> <json_params>


Description

    Send with parameters: binary (true: data is Base64 and is sent as binary), timeout_ms (10000; after a send time-out the connection is unusable and is put in error)

Parameters

    name:   The connection - String - required
    data:   The text or the Base64 - String - required
    json_params:   The parameters - String - required
admin
ws send "chat" "AAEC/w==" "{\"binary\": true, \"timeout_ms\": 3000}"
mentdb
{"sent": true, "bytes": 4}

ws receive <name>


Description

    The next message, waiting 5 seconds at most

Parameters

    name:   The connection - String - required
admin
ws receive "chat"
mentdb
{"received": true, "type": "text", "data": "hello", "bytes": 5}

ws receive <name> <json_params>


Description

    The next message with parameters: timeout_ms (5000, 300000 at most, 0: do not wait)

Parameters

    name:   The connection - String - required
    json_params:   The parameters - String - required
admin
ws receive "chat" "{\"timeout_ms\": 200}"
mentdb
{"received": false, "type": "timeout", "data": null, "bytes": 0}
Fixed result from a real call to a local test server (127.0.0.1): the server closed: the last message, then the code and the reason
admin
ws connect "bye" "ws://127.0.0.1:22001/closeme"; ws receive "bye"; ws receive "bye"
mentdb
{"received": false, "type": "closed", "data": null, "bytes": 0, "code": 4001, "reason": "done here"}

ws receive_all <name>


Description

    Every message already there, without waiting: JSON {count, messages, state, more}

Parameters

    name:   The connection - String - required
admin
ws receive_all "chat"
mentdb
{"count": 1, "messages": [{"type": "text", "data": "two", "bytes": 3}], "state": "open", "more": false}

ws receive_all <name> <json_params>


Description

    The same with parameters: timeout_ms (0: how long to wait for the first message), max_messages (1000)

Parameters

    name:   The connection - String - required
    json_params:   The parameters - String - required
admin
ws receive_all "chat" "{\"timeout_ms\": 1000, \"max_messages\": 10}"
mentdb
{"count": 1, "messages": [{"type": "binary", "data": "AAEC/w==", "bytes": 4}], "state": "open", "more": false}

ws ping <name>


Description

    Send a ping; the answer is counted in pongs of ws show

Parameters

    name:   The connection - String - required
admin
ws ping "chat"
mentdb
{"sent": true}

ws ping <name> <payload>


Description

    Send a ping with a text of 125 bytes at most

Parameters

    name:   The connection - String - required
    payload:   The text - String - required
admin
ws ping "chat" "still there?"
mentdb
{"sent": true}

ws show


Description

    All the connections of the user: JSON array

admin
ws show
mentdb
[{"name": "chat", "url": "ws://127.0.0.1:22001/echo", "state": "open", "subprotocol": null, "tls_verified": null, "connected_at": "2026-11-05T05:41:24.027Z", "idle_s": 0, "queued": 0, "queued_bytes": 0, "paused": false, "received": 4, "sent": 4, "pings": 0, "pongs": 2, "close_code": null, "close_reason": null, "error": null}]

ws show <name>


Description

    The state of a connection

Parameters

    name:   The connection - String - required
admin
ws show "chat"
mentdb
{"name": "chat", "url": "ws://127.0.0.1:22001/echo", "state": "open", "subprotocol": null, "tls_verified": null, "connected_at": "2026-11-05T05:41:24.027Z", "idle_s": 0, "queued": 0, "queued_bytes": 0, "paused": false, "received": 4, "sent": 4, "pings": 0, "pongs": 0, "close_code": null, "close_reason": null, "error": null}

ws close <name>


Description

    Close a connection with a close handshake (3 seconds at most) and forget it: JSON {name, closed, clean, code}. The waiting messages are dropped

Parameters

    name:   The connection - String - required
admin
ws close "chat"
mentdb
{"name": "chat", "closed": true, "clean": true, "code": 1000}

ws close <name> <json_params>


Description

    Close with parameters: code (1000, or 3000 to 4999), reason (123 bytes at most), timeout_ms (3000)

Parameters

    name:   The connection - String - required
    json_params:   The parameters - String - required
admin
ws close "feed" "{\"code\": 4000, \"reason\": \"done\"}"
mentdb
{"name": "feed", "closed": true, "clean": true, "code": 4000}

ws close_all


Description

    Close all the connections of the user: JSON {closed}

admin
ws close_all
mentdb
{"closed": 1}