CLI Reference

The domscribe CLI manages the relay server, workspace initialization, and MCP server.

Installation

Install globally:

npm install -g domscribe

Or run without installing via npx:

npx domscribe <command>

Commands

domscribe init

Interactive setup wizard that configures both the agent-side (MCP plugin) and app-side (bundler plugin) of Domscribe.

domscribe init [--app-root <path>]

The wizard:

1. Detects your project structure (monorepo or single app)
2. Asks you to choose your coding agent and installs the MCP plugin
3. Asks you to choose your framework and bundler, installs the correct @domscribe/* package
4. Prints the configuration snippet to add to your bundler config

In monorepos, this creates a domscribe.config.json at the repo root so that all CLI commands and MCP connections automatically resolve the app root.

domscribe serve

Start the relay server.

domscribe serve [options]

The relay server provides HTTP endpoints for annotation management, WebSocket for real-time overlay updates, and bridges to the MCP server for agent access.

A file lock at .domscribe/relay.lock prevents duplicate instances across dev server restarts. If a relay is already running, the command reports the existing instance's host and port.

domscribe status

Check whether the relay daemon is running and display its connection details.

domscribe status

Reports the relay's PID, port, and health status. Returns a non-zero exit code if the daemon is not running.

domscribe stop

Stop the running relay daemon.

domscribe stop

Sends a graceful shutdown signal. The daemon releases its file lock and closes all connections before exiting.

domscribe mcp

Run the MCP server over stdio. This is used in agent MCP configurations.

domscribe mcp

This starts the MCP server in the current process using stdio transport. It connects to the relay daemon on localhost and exposes all 12 Domscribe tools and 4 prompts.

For most agent setups, use the standalone @domscribe/mcp package instead:

{
  "mcpServers": {
    "domscribe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@domscribe/mcp"]
    }
  }
}

Daemon Lifecycle

The relay daemon uses a lock-based singleton pattern:

1. On start, it writes a lock file at .domscribe/relay.lock containing the PID and port.
2. RelayControl.ensureRunning() checks the lock file -- if a healthy daemon exists, it returns the existing host and port instead of starting a new one.
3. Health checks use HTTP polling with a 500ms timeout and 5s max wait.
4. On shutdown (SIGTERM or domscribe stop), the daemon releases the lock and closes all HTTP, WebSocket, and MCP connections.

The bundler plugins call RelayControl.ensureRunning() automatically when relay.autoStart is true (the default), so you typically do not need to run domscribe serve manually.

Monorepo Support

All commands automatically resolve the app root from a domscribe.config.json file when run from a monorepo root. Generate this config with:

domscribe init --app-root apps/web

Once the config exists, you can run domscribe serve, domscribe status, and domscribe stop from anywhere in the repo.