npx specter

Opens in your browser. No install. No signup. No cloud.

Why Specter?

Every WebSocket tool makes you choose between bloat, cloud lock-in, or a bare terminal. Postman requires an account. Online testers send your data to someone else's server. websocat is powerful but gives you nothing visual.

Specter doesn't make you choose.

| | Postman WS | Online testers | websocat | Specter | |---|:---:|:---:|:---:|:---:| | Runs in browser | ✗ | ✓ | ✗ | ✅ | | Data stays local | ✗ | ✗ | ✓ | ✅ | | JSON tree view | ✗ | ✗ | ✗ | ✅ | | Saved connections | ✓ | ✗ | ✗ | ✅ | | Collections | ✓ | ✗ | ✗ | ✅ | | No account needed | ✗ | ✓ | ✓ | ✅ |

Quick Start

npx specter

That's it. Specter starts a local server on port 4321 and opens your browser automatically. No global install, no config file, no waiting.

To use a different port:

PORT=4322 npx specter

Features

⚡ Zero-config launch

npx specter and your browser opens. The CLI serves the pre-built UI from a lightweight Node.js HTTP server — no Electron, no native dependencies, no install step.

💾 Persistent connections

Every connection you create (URL, headers, subprotocols) is saved to IndexedDB in your browser. Close the tab, restart your machine, come back tomorrow — your connections are still there. Nothing is stored on any server.

🔍 Message inspector

Incoming and outgoing messages are displayed in a scrollable log. JSON payloads are automatically parsed and rendered as a collapsible syntax-highlighted tree, so you can drill into nested objects without squinting at a wall of text.

📁 Collections

Store reusable message templates as JSON files in a .specter/ directory at your project root. They appear in the UI automatically. Commit .specter/ to git and your whole team shares the same test sequences — no copy-pasting payloads.

⌨️ Keyboard-driven

• Cmd+Enter / Ctrl+Enter — send message
• Clean tab-based UI that stays out of your way

🔒 Local-only

No telemetry. No analytics. No sync. No data ever leaves your machine.

Collections

A collection is a JSON file in .specter/ that groups related message templates together.

.specter/auth-flow.json

{
  "name": "Auth Flow",
  "templates": [
    {
      "name": "Login",
      "payload": "{\"action\":\"login\",\"token\":\"abc123\"}",
      "type": "json"
    },
    {
      "name": "Ping",
      "payload": "{\"action\":\"ping\"}",
      "type": "json"
    },
    {
      "name": "Logout",
      "payload": "{\"action\":\"logout\"}",
      "type": "json"
    }
  ]
}

| Field | Type | Description | |---|---|---| | name | string | Display name shown in the sidebar | | templates | array | List of message templates | | templates[].name | string | Label for the template button | | templates[].payload | string | The raw message body to send | | templates[].type | "json" | "text" | Controls syntax highlighting in the inspector |

Tip: Commit .specter/ to git. Your teammates get the same collections when they clone the repo.

Connections

Each saved connection stores:

• URL — the WebSocket endpoint (e.g. ws://localhost:8080)
• Headers — custom HTTP headers sent during the handshake
• Subprotocols — optional Sec-WebSocket-Protocol values

Connections are stored in IndexedDB under the key specter-connections. They persist across browser sessions and are never synced anywhere.

Local Development

git clone https://github.com/your-org/specter
cd specter
npm install
npm run dev

| Command | Description | |---|---| | npm run dev | Start Vite dev server with HMR at http://localhost:5173 | | npm run build | TypeScript compile + Vite production build → dist/ | | npm run test | Run Vitest unit tests | | npm run cli | Serve the production build locally (same as npx specter) |

Project structure

specter/
├── cli/
│   └── bin.js          # Node.js CLI entry point (npx specter)
├── src/
│   ├── components/     # React UI components
│   │   ├── ConnectionModal.tsx
│   │   ├── ConnectionPanel.tsx
│   │   ├── JsonViewer.tsx
│   │   ├── MessageComposer.tsx
│   │   ├── MessageLog.tsx
│   │   └── Sidebar.tsx
│   ├── hooks/
│   │   └── useWebSocket.ts  # WebSocket lifecycle hook
│   ├── db.ts           # IndexedDB persistence (via idb)
│   ├── store.ts        # Zustand global state
│   ├── types.ts        # Shared TypeScript types
│   └── utils.ts        # Helpers (JSON detection, formatting)
├── .specter/           # Collection files (commit this to git)
├── tests/              # Vitest unit tests
├── dist/               # Production build output (git-ignored)
└── public/             # Static assets

Publishing to npm

Required before npx specter works for anyone else.

Prerequisites

1. Create a free account at npmjs.com
2. Verify your email address

Steps

1. Build the production bundle

npm run build

This generates dist/ — the static files the CLI serves. The dist/ directory is included in the npm package via the "files" field in package.json.

2. Log in to npm

npm login

Enter your npm username, password, and OTP if 2FA is enabled.

3. Check the package name is available

npm view specter

If it returns a 404, the name is free. If it's taken, update the "name" field in package.json to something unique (e.g. specter-ws).

4. Publish

npm publish

For a scoped package (e.g. @yourname/specter):

npm publish --access public

5. Test it

npx specter
# or
npx @yourname/specter

Updating an existing release

Bump the version in package.json following semver, then publish again:

# patch: bug fixes (1.0.0 → 1.0.1)
npm version patch

# minor: new features, backward-compatible (1.0.0 → 1.1.0)
npm version minor

# major: breaking changes (1.0.0 → 2.0.0)
npm version major

npm run build && npm publish

What gets published

The "files" field in package.json controls what's included in the npm package:

"files": ["dist", "cli", "README.md", "LICENSE"]

Everything else (source code, tests, screenshots, node_modules) is excluded automatically.

Tech Stack

| Layer | Technology | Why | |---|---|---| | UI framework | React 18 + TypeScript | Component model, type safety | | Build tool | Vite 5 | Fast HMR, optimized production builds | | Styling | Tailwind CSS | Utility-first, no runtime overhead | | State | Zustand | Minimal boilerplate, no context hell | | Persistence | IndexedDB via idb | Browser-native, no backend needed | | CLI server | Node.js http module | Zero runtime dependencies | | Icons | Lucide React | Consistent, tree-shakeable icon set | | Tests | Vitest | Native ESM, Vite-integrated |

Contributing

1. Fork the repo
2. Create a branch: git checkout -b feat/your-feature
3. Make your changes and add tests
4. Run npm test to verify
5. Open a pull request

npm · Issues · MIT License

Made for developers who just want to debug WebSockets without the drama.