modelriver websocket

Test real-time WebSocket connections to ModelRiver. Send requests and receive AI responses directly in your terminal.

Overview

The websocket command sends an async request and immediately connects via WebSocket to receive the real-time response. It's the fastest way to test your workflow end-to-end from the command line.

Usage

Bash

# Test with workflow
modelriver websocket --workflow my-workflow --message "Hello from CLI"
 
# With custom payload
modelriver websocket --workflow my-workflow --payload '{"messages": [{"role": "user", "content": "Test"}]}'
 
# Connect to existing channel
modelriver websocket --channel-id abc-123 --project-id xyz-789
 
# Verbose output
modelriver websocket --workflow my-workflow --message "Test" --verbose

Example output

✓ Making async request...
✓ Request queued: abc-123-def
 
> Channel ID: abc-123-def
> Project ID: xyz-789
 
✓ Connecting to WebSocket...
✓ WebSocket connected
✓ Channel joined
 
> Waiting for response...
 
✅ Response received:
{
  "status": "success",
  "data": { ... },
  "meta": { ... }
}

Options

Option	Description
`--workflow <name>`	Workflow to test
`--message <text>`	Simple text message
`--payload <json>`	Custom JSON payload
`--channel-id <id>`	Existing channel ID
`--project-id <id>`	Project ID
`--verbose`	Show detailed logs

Event-driven workflows

For event-driven workflows, websocket first receives status: "ai_generated" and keeps waiting. Complete the flow with:

Bash

modelriver callback --channel-id CHANNEL_ID --data '{"summary":"..."}'

Then the CLI prints the final completed response.

Troubleshooting

"WebSocket connection failed"

Verify the API URL is correct
Check that the ws_token hasn't expired (24-hour limit for CLI tokens)
Check network connectivity
If using production, ensure you're using wss:// (secure WebSocket)

Timeout waiting for response

For event-driven workflows, send a callback within 10 minutes
Check server logs if the workflow failed before broadcasting

Next steps

Listen: Monitor webhook events via WebSocket
Trigger: Send requests without WebSocket monitoring
Callback: Complete event-driven flows
Client SDK: Frontend WebSocket integration