# websockets-cli
[](https://pypi.org/project/websockets-cli/)
[](https://codecov.io/gh/lewoudar/ws)
[](https://pyws.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/lewoudar/ws)
[](http://www.apache.org/licenses/LICENSE-2.0)
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](https://websockets.readthedocs.io/en/stable/).
There are graphical tools like [Postman](https://www.postman.com/), 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`:
```shell
$ pip install websockets-cli
```
or use a better package manager like [poetry](https://python-poetry.org/docs/):
```shell
# 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](https://trio.readthedocs.io/en/stable/) for structured (async) concurrency support.
- [trio-websocket](https://trio-websocket.readthedocs.io/en/stable/) the library implementing the websocket protocol.
- [pydantic](https://docs.pydantic.dev/latest/) / [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for
input validation and settings management.
- [certifi](https://pypi.org/project/certifi/) to manage TLS and certificates.
- [click](https://click.palletsprojects.com/en/8.1.x/) to write the cli.
- [click-didyoumean](https://pypi.org/project/click-didyoumean/) for command suggestions in case of typos.
- [rich](https://rich.readthedocs.io/en/latest/) for beautiful output display.
- [shellingham](https://pypi.org/project/shellingham/) to detect the shell used.
## Usage
The usage is straightforward and the cli is well documented.
```shell
$ 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` ;)
```shell
$ 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](https://blog.postman.com/introducing-postman-websocket-echo-service/) team at wss://ws.postman-echo.com/raw or
spawn a new one with the following command:
```shell
# 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:
```shell
# :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:
```shell
# 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.
```shell
$ 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](https://datatracker.ietf.org/doc/html/rfc7692) and
[RFC 8441](https://datatracker.ietf.org/doc/html/rfc8441) because `trio_websocket` the underlying library used for
websockets does not support it.
Raw data
{
"_id": null,
"home_page": "https://pyws.readthedocs.io",
"name": "websockets-cli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "websocket,cli,trio,anyio",
"author": "le_woudar",
"author_email": "lewoudar@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/17/7a/c356062673059fe6bb7dfb02114cc2a78f386e2660d0aa78b37a3bbd5bf4/websockets_cli-0.3.0.tar.gz",
"platform": null,
"description": "# websockets-cli\n\n[](https://pypi.org/project/websockets-cli/)\n\n[](https://codecov.io/gh/lewoudar/ws)\n[](https://pyws.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/lewoudar/ws)\n[](http://www.apache.org/licenses/LICENSE-2.0)\n\nA simple yet powerful websocket cli.\n\n## Why?\n\nEach time I work on a web project involving websockets, I found myself wanting a simple (cli) tool to test what I have\ncoded. What I often do is to write a python script using [websockets](https://websockets.readthedocs.io/en/stable/).\nThere are graphical tools like [Postman](https://www.postman.com/), but I'm not confortable with.\nSo I decided to write a cli tool for this purpose.\n\n## Installation\n\nYou can install the cli with `pip`:\n\n```shell\n$ pip install websockets-cli\n```\n\nor use a better package manager like [poetry](https://python-poetry.org/docs/):\n\n```shell\n# you probably want to add this dependency as a dev one, this is why I put -D into square brackets\n$ poetry add websockets-cli -G dev\n```\n\nws starts working from **python3.8** and also supports **pypy3**. It has the following dependencies:\n\n- [trio](https://trio.readthedocs.io/en/stable/) for structured (async) concurrency support.\n- [trio-websocket](https://trio-websocket.readthedocs.io/en/stable/) the library implementing the websocket protocol.\n- [pydantic](https://docs.pydantic.dev/latest/) / [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for\n input validation and settings management.\n- [certifi](https://pypi.org/project/certifi/) to manage TLS and certificates.\n- [click](https://click.palletsprojects.com/en/8.1.x/) to write the cli.\n- [click-didyoumean](https://pypi.org/project/click-didyoumean/) for command suggestions in case of typos.\n- [rich](https://rich.readthedocs.io/en/latest/) for beautiful output display.\n- [shellingham](https://pypi.org/project/shellingham/) to detect the shell used.\n\n## Usage\n\nThe usage is straightforward and the cli is well documented.\n\n```shell\n$ ws\nUsage: ws [OPTIONS] COMMAND [ARGS]...\n\n A convenient websocket cli.\n\n Example usage:\n\n # listens incoming messages from endpoint ws://localhost:8000/path\n $ ws listen ws://localhost:8000/path\n\n # sends text \"hello world\" in a text frame\n $ ws text wss://ws.postman-echo.com/raw \"hello world\"\n\n # sends the content from json file \"hello.json\" in a binary frame\n $ ws byte wss://ws.postman-echo.com/raw file@hello.json\n\nOptions:\n --version Show the version and exit.\n -h, --help Show this message and exit.\n\nCommands:\n byte Sends binary message to URL endpoint.\n echo-server Runs an echo websocket server.\n install-completion Install completion script for bash, zsh and fish...\n listen Listens messages on a given URL.\n ping Pings a websocket server located at URL.\n pong Sends a pong to websocket server located at URL.\n session Opens an interactive session to communicate with...\n tail An emulator of the tail unix command that output...\n text Sends text message on URL endpoint.\n```\n\nThe first command to use is `install-completion` to have auto-completion for commands and options using the `TAB` key.\nAuto-completion is available on `bash`, `fish` and `zsh`. For Windows users, I don't forget you (I'm also a Windows\nuser), support is planned for `Powershell` ;)\n\n```shell\n$ ws install-completion\n# when the command succeeded, you should see the following message\nSuccessfully installed completion script!\n```\n\nTo play with the api you can use the websocket server kindly provided by the\n[Postman](https://blog.postman.com/introducing-postman-websocket-echo-service/) team at wss://ws.postman-echo.com/raw or\nspawn a new one with the following command:\n\n```shell\n# it will listen incoming messages on port 8000, to stop it, just type Ctrl+C\n$ ws echo-server -p 8000\nRunning server on localhost:8000 \ud83d\udcab\n```\n\nTo *ping* the server, you can do this:\n\n```shell\n# :8000 is a\n$ ws ping :8000\nPING ws://localhost:8000 with 32 bytes of data\nsequence=1, time=0.00s\n```\n\nTo send a message, you can type this:\n\n```shell\n# Sends a text frame\n$ ws text :8000 \"hello world\" # on Windows it is probably better to use single quotes 'hello world'\nSent 11.0 B of data over the wire.\n\n# Sends a binary frame\n$ ws byte :8000 \"hello world\"\nSent 11.0 B of data over the wire.\n```\n\nIf you know that you will have a long interaction with the server, it is probably better to use the `session` subcommand.\n\n```shell\n$ ws session wss://ws.postman-echo.com/raw\nWelcome to the interactive websocket session! \ud83c\udf1f\nFor more information about commands, type the help command.\nWhen you see <> around a word, it means this argument is optional.\nTo know more about a particular command type help <command>.\nTo close the session, you can type Ctrl+D or the quit command.\n\n> ping \"with payload\"\nPING wss://ws.postman-echo.com/raw with 12 bytes of data\nTook 0.16s to receive a PONG.\n\n> quit\nBye! \ud83d\udc4b\n```\n## Documentation\n\nThe full documentation can be found at https://pyws.readthedocs.io\n\n## Limitations\n\nThe cli does not support [RFC 7692](https://datatracker.ietf.org/doc/html/rfc7692) and\n[RFC 8441](https://datatracker.ietf.org/doc/html/rfc8441) because `trio_websocket` the underlying library used for\nwebsockets does not support it.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A simple yet powerful websocket cli",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/lewoudar/ws/issues",
"Changelog": "https://github.com/lewoudar/ws/blob/main/CHANGELOG.md",
"Documentation": "https://pyws.readthedocs.io",
"Homepage": "https://pyws.readthedocs.io",
"Repository": "https://github.com/lewoudar/ws"
},
"split_keywords": [
"websocket",
"cli",
"trio",
"anyio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e8c28a84fce1c56ffa3a74f32165f83e0cfd8dff5873cab22cd85c62c7af55a",
"md5": "2423a58b291fed48b40d9eda4e4107c6",
"sha256": "a6a311e32cb752671c5f62a1986c8c63507aca7d80f964356089f40f2d092aa7"
},
"downloads": -1,
"filename": "websockets_cli-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2423a58b291fed48b40d9eda4e4107c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 29054,
"upload_time": "2023-11-24T12:38:49",
"upload_time_iso_8601": "2023-11-24T12:38:49.690015Z",
"url": "https://files.pythonhosted.org/packages/0e/8c/28a84fce1c56ffa3a74f32165f83e0cfd8dff5873cab22cd85c62c7af55a/websockets_cli-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "177ac356062673059fe6bb7dfb02114cc2a78f386e2660d0aa78b37a3bbd5bf4",
"md5": "eed208a4f9b34cdacda6b5f6032f2415",
"sha256": "0b2e729cee65f67406840a502cd915ee5ecb450849517be2470e61d180129343"
},
"downloads": -1,
"filename": "websockets_cli-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "eed208a4f9b34cdacda6b5f6032f2415",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 23852,
"upload_time": "2023-11-24T12:38:50",
"upload_time_iso_8601": "2023-11-24T12:38:50.773161Z",
"url": "https://files.pythonhosted.org/packages/17/7a/c356062673059fe6bb7dfb02114cc2a78f386e2660d0aa78b37a3bbd5bf4/websockets_cli-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 12:38:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lewoudar",
"github_project": "ws",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "websockets-cli"
}
JSON
