websockets-cli

A simple yet powerful websocket cli.

Why?

Each time I work on a web project involving websockets, I found myself wanting a simple (cli) tool to test what I have coded. What I often do is to write a python script using websockets. There are graphical tools like Postman, but I'm not confortable with. So I decided to write a cli tool for this purpose.

Installation

You can install the cli with pip:

$ pip install websockets-cli

or use a better package manager like poetry:

# you probably want to add this dependency as a dev one, this is why I put -D into square brackets
$ poetry add websockets-cli -G dev

ws starts working from python3.8 and also supports pypy3. It has the following dependencies:

• trio for structured (async) concurrency support.
• trio-websocket the library implementing the websocket protocol.
• pydantic / pydantic-settings for input validation and settings management.
• certifi to manage TLS and certificates.
• click to write the cli.
• click-didyoumean for command suggestions in case of typos.
• rich for beautiful output display.
• shellingham to detect the shell used.

Usage

The usage is straightforward and the cli is well documented.

$ ws
Usage: ws [OPTIONS] COMMAND [ARGS]...

  A convenient websocket cli.

  Example usage:

  # listens incoming messages from endpoint ws://localhost:8000/path
  $ ws listen ws://localhost:8000/path

  # sends text "hello world" in a text frame
  $ ws text wss://ws.postman-echo.com/raw "hello world"

  # sends the content from json file "hello.json" in a binary frame
  $ ws byte wss://ws.postman-echo.com/raw file@hello.json

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  byte                Sends binary message to URL endpoint.
  echo-server         Runs an echo websocket server.
  install-completion  Install completion script for bash, zsh and fish...
  listen              Listens messages on a given URL.
  ping                Pings a websocket server located at URL.
  pong                Sends a pong to websocket server located at URL.
  session             Opens an interactive session to communicate with...
  tail                An emulator of the tail unix command that output...
  text                Sends text message on URL endpoint.

The first command to use is install-completion to have auto-completion for commands and options using the TAB key. Auto-completion is available on bash, fish and zsh. For Windows users, I don't forget you (I'm also a Windows user), support is planned for Powershell ;)

$ ws install-completion
# when the command succeeded, you should see the following message
Successfully installed completion script!

To play with the api you can use the websocket server kindly provided by the Postman team at wss://ws.postman-echo.com/raw or spawn a new one with the following command:

# it will listen incoming messages on port 8000, to stop it, just type Ctrl+C
$ ws echo-server -p 8000
Running server on localhost:8000 💫

To ping the server, you can do this:

# :8000 is a
$ ws ping :8000
PING ws://localhost:8000 with 32 bytes of data
sequence=1, time=0.00s

To send a message, you can type this:

# Sends a text frame
$ ws text :8000 "hello world"  # on Windows it is probably better to use single quotes 'hello world'
Sent 11.0 B of data over the wire.

# Sends a binary frame
$ ws byte :8000 "hello world"
Sent 11.0 B of data over the wire.

If you know that you will have a long interaction with the server, it is probably better to use the session subcommand.

$ ws session wss://ws.postman-echo.com/raw
Welcome to the interactive websocket session! 🌟
For more information about commands, type the help command.
When you see <> around a word, it means this argument is optional.
To know more about a particular command type help <command>.
To close the session, you can type Ctrl+D or the quit command.

> ping "with payload"
PING wss://ws.postman-echo.com/raw with 12 bytes of data
Took 0.16s to receive a PONG.

> quit
Bye! 👋

Documentation

The full documentation can be found at https://pyws.readthedocs.io

Limitations

The cli does not support RFC 7692 and RFC 8441 because trio_websocket the underlying library used for websockets does not support it.