Skip to content
MSW Agent Tools

msw-cli Overview

msw-cli is a command-line interface that lets you — or an AI agent — add, update, remove, and reset MSW request handlers in a running browser tab without reloading the page.

It uses the same session-based model as Playwright: open a session first, then drive handler operations against it.

How it works

Section titled “How it works”
┌──────────────┐  HTTP /api/tools/*  ┌──────────────────────┐  WebSocket  ┌──────────────────┐
│              │────────────────────►│                      │────────────►│                  │
│  msw-cli     │                     │  @msw-mcp/core       │             │  Browser + MSW   │
│  (terminal)  │                     │  daemon (port 6789)  │             │  service worker  │
│              │◄────────────────────│                      │◄────────────│                  │
└──────────────┘                     └──────────────────────┘             └──────────────────┘
  1. msw-cli open spawns a background daemon that starts an HTTP + WebSocket server.
  2. Your browser app (with @msw-mcp/client) connects to the daemon over WebSocket.
  3. Subsequent CLI commands (add, update, remove, etc.) POST to the daemon’s HTTP API, which forwards them to the browser over the open WebSocket.
  4. MSW executes the handler code in the browser context immediately.

Session metadata (port, pid) is stored at ~/.msw-cli/sessions/.

Key features

Section titled “Key features”

No MCP required

Works in any terminal, CI script, or agent that can run shell commands. No MCP client setup needed.

Playwright-style sessions

Open a named session per project directory. Multiple sessions can run concurrently on different ports.

Auto port selection

If port 6789 is busy, msw-cli open auto-selects the next available port and tells you to update your bridge URL.

Live handler evaluation

Handler code strings are evaluated in the browser context against the live MSW worker — changes take effect instantly.

Workflow at a glance

Section titled “Workflow at a glance”
Terminal window
# New project? Print the full scaffolding guide first
msw-cli setup


# Start a session
msw-cli open


# Add a handler
msw-cli add "http.get('/api/user', () => HttpResponse.json({ id: 1 }))"


# Update an existing handler
msw-cli update "/api/user" -h "http.get('/api/user', () => HttpResponse.json({ id: 2 }))"


# Remove a handler
msw-cli remove "/api/user"


# Reset to base handlers
msw-cli reset


# Check connection and active handlers
msw-cli status


# Close the session
msw-cli close

Next steps

Section titled “Next steps”
  • Commands — detailed reference for every command and flag
  • Session Management — named sessions, concurrent environments, and cleanup