wsdctl

A CLI tool for managing WebSocket connections. A background daemon keeps connections alive between commands, making it easy to test WebSocket-based flows step by step.

Zero config. The daemon starts automatically on first use.

Install

npm install -g wsdctl

Requires Node.js 22+ (uses native WebSocket support).

Quick Start

# Connect to a WebSocket server
wsdctl connect wss://example.com/ws --id app

# Send a message and wait for a response
wsdctl send app '{"action":"ping"}' --wait --timeout 3000

# View all traffic
wsdctl messages app

# Disconnect
wsdctl disconnect app

Commands

| Command | Description | |---------|-------------| | connect <url> | Open a WebSocket connection | | send <id> <msg> | Send a message | | wait <id> | Wait for an incoming message | | messages <id> | View message history | | status <id> | Inspect a connection | | list | List active connections | | disconnect <id> | Close a connection | | reconnect <id> | Reopen a closed connection | | closed | List recently closed connections | | clear <id> | Clear message history | | stop | Stop the daemon | | help [cmd] | Show help |

Run wsdctl help <command> for detailed usage of any command.

Connect

wsdctl connect <url> [--id <alias>] [--header <K:V>]... [--message <msg>] [--wait] [--timeout <ms>] [--match <str>]

wsdctl connect wss://example.com/ws                                    # auto-id (c1, c2, ...)
wsdctl connect wss://example.com/ws --id app                           # custom id
wsdctl connect wss://example.com/ws --header "Authorization:Bearer t"  # custom header
wsdctl connect wss://example.com/ws --header "Auth:t" --header "X:v"   # multiple headers
wsdctl connect wss://example.com/ws --timeout 5000                     # handshake timeout
wsdctl connect wss://example.com/ws --message '{"type":"hello"}'       # send on connect
wsdctl connect wss://example.com/ws --message '{"type":"hello"}' --wait --timeout 5000  # send + wait

Send

wsdctl send <id> <message> [--wait] [--timeout <ms>] [--match <str>]

wsdctl send app hello                                          # simple text
wsdctl send app '{"type":"ping"}'                              # JSON
wsdctl send app '{"type":"ping"}' --wait                       # send and wait for reply
wsdctl send app '{"type":"ping"}' --wait --match "pong"        # wait for specific reply
wsdctl send app '{"type":"ping"}' --wait --match '/ok/i'       # regex match

Wait

wsdctl wait <id> [--timeout <ms>] [--match <str>]

Blocks until the next incoming message (or timeout). With --match, skips messages that don't match.

Match Patterns

--match works with wait, send --wait, and connect --wait:

• Substring: --match "pong" -- matches if the message contains "pong"
• Regex: --match '/pattern/flags' -- regular expression (e.g. '/status":\s*"ok/i')

Disconnect

wsdctl disconnect <id>                       # fire-and-forget
wsdctl disconnect <id> --wait                # block until close frame (10s default)
wsdctl disconnect <id> --wait --timeout 5000 # custom timeout
wsdctl disconnect --all                      # close all connections

Reconnect

wsdctl reconnect <id>

Reopens a closed connection using the same URL and headers. The connection must be in the closed history (last 50 are kept).

JSON Output

All commands support --json for machine-readable output:

wsdctl list --json
wsdctl status app --json
wsdctl messages app --json
wsdctl send app '{"type":"ping"}' --wait --json

Example Flow

# 1. Connect, send initial message, wait for confirmation
wsdctl connect wss://api.example.com/ws --id app \
  --header "Authorization:Bearer token" \
  --message '{"action":"subscribe","channel":"updates"}' \
  --wait --timeout 5000 --match "subscribed"

# 2. Send request and get response
wsdctl send app '{"action":"query","id":1}' --wait --timeout 3000

# 3. Review full traffic
wsdctl messages app

# 4. Check connection state
wsdctl status app

# 5. Clean disconnect
wsdctl disconnect app --wait

# 6. Reconnect later (same url + headers)
wsdctl reconnect app

# 7. Done — close everything
wsdctl disconnect --all
wsdctl stop

How It Works

wsdctl runs a lightweight background daemon that holds WebSocket connections open. The CLI communicates with the daemon over a Unix socket (/tmp/wsdctl.sock). This allows connections to persist across commands without keeping a terminal open.

• Daemon starts automatically on the first command that needs it
• Daemon logs: /tmp/wsdctl.log
• Stop manually with wsdctl stop

Claude Code Integration

wsdctl ships with a Claude Code skill for AI-assisted WebSocket testing:

wsdctl setup-skill

This copies the skill file to ~/.claude/skills/wsdctl/SKILL.md. After that, Claude Code can use wsdctl to test WebSocket connections on your behalf.

License

ISC