# CLI Reference

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

## Installation

Install globally:

```bash
npm install -g domscribe
```

Or run without installing via npx:

```bash
npx domscribe <command>
```

* * *

## Commands

### `domscribe init`

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

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

| Option          | Type    | Description                                                     |
| --------------- | ------- | --------------------------------------------------------------- |
| `--app-root`   | `string`| Path to the frontend app directory (for monorepos, e.g. `apps/web`) |

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.

```bash
domscribe serve [options]
```

| Option       | Type     | Default      | Description                                                        |
| ------------ | -------- | ------------ | ------------------------------------------------------------------ |
| `--daemon`   | `boolean`| `false`     | Run as a background daemon                                          |
| `--port`     | `number` | `0` (dynamic)| Port to listen on. When 0, the OS assigns an available port.      |
| `--host`     | `string` | `127.0.0.1` | Host to bind to                                                    |

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.

```bash
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.

```bash
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.

```bash
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:

```json
{
  "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:

```bash
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.