wscli

wscli

A lightweight and powerful Go command-line tool for interacting with WebSocket servers. Designed for testing, debugging, and scripting, wscli provides functionality similar to wscat but with additional features. Supports quick load testing.

🚀 Installation

Using Docker

$ docker run -it akshaykhairmode/wscli:latest -c "ws://example.com/ws"

Using go install

go install github.com/akshaykhairmode/wscli@latest

Download Prebuilt Binaries

If you don’t have Go installed, download the latest binaries from the Releases Page.

🔧 Usage

Connect to a WebSocket server

$ wscli -c ws://localhost:8080/ws

Connect with custom headers

$ wscli -c ws://localhost:8080/ws -H "Authorization: Bearer mytoken" -H "X-Custom: value"

Send a command immediately after connecting

$ wscli -c ws://localhost:8080/ws -x '{"action": "subscribe", "channel": "updates"}'

Send a close message with code 1000 and reason "normal closure"

$ wscli --slash -c ws://localhost:8080/ws
/close 1000 normal closure

Send a binary file

$ wscli --slash -c ws://localhost:8080/ws
/bfile /home/user/test.bin

✨ Features

• 🔹 Native Binaries: Easy installation across systems.
• 📤 Piped Input: Send piped input using | (disables interactive terminal features).
• 📨 Multiple Messages on Connect: Send multiple messages immediately after connecting.
• 🎭 Background Execution:
  • Run wscli in the background using nohup:

    $ nohup wscli -c ws://localhost/ws -w 1s > nohup.out 2>&1 &
    

  • Redirect output and run in the background:

    $ wscli -c ws://localhost/ws >> output.txt & 2>&1
    

• 📜 History Persistence: Maintain a command history for quick reuse.
• ⚡ Command Execution on Connect: Use -x to execute commands automatically.
• 📌 JSON Pretty Printing: Format JSON responses using --jspp.
• ⌨️ Terminal Shortcuts: Supports readline shortcuts like Ctrl+W (delete word) and Ctrl+R (reverse search). See full list.
• 🗂️ Binary File Transfer: Send a file as a binary message.
• 📊 Load Testing: Perform load tests using the --perf flag.

🛠 Available Flags

🛠 Slash Commands (Enable via --slash)

📊 Load Testing (Enable via --perf)

Note: --lm and --am also support file input. Provide an absolute path to send messages from a file. The file reading will restart from the first line when EOF is reached. If file is less than 10MB then we store it in memory. "\n" is the delimeter.

Load Message Templates

Example

$ wscli -c ws://localhost:8080/ws --perf --tc 1000 --lm "hello world {{RandomNumber 50}}" --rups 100 --mps 10

OR

$ wscli -c ws://localhost:8080/ws --perf --tc 1000 --lm "/tmp/load.txt" --rups 100 --mps 10

# Flags used:
# --perf (enable performance testing)
# --tc 1000 (create 1000 connections)
# --lm "hello world {{RandomNumber 50}}" (load message, generate a random number from 0 to 50)
# --lm "/tmp/load.txt" (load message, read from file)
# --rups 100 (ramp up 100 connections per second)
# --mps 10 (send 10 messages per second)

output:

Output with -v

🚧 Upcoming Features

• WebSocket Listener: Implement a feature to start a WebSocket server.