CLI reference

The Watcher package @elixir-nexus/watcher provides one command-line tool, watcher. Run it with npx from your project root after installing Watcher locally.

Usage: watcher [options] [command]

Local-first operational workspace for existing Playwright projects.

Options:
  -V, --version    output the version number
  -h, --help       display help for command

Commands:
  start [options]  Start Watcher from your Playwright project root (containing
                   package.json)
  help [command]   display help for command

watcher start

Discovers the project in the current directory and starts the local server and dashboard.

npx watcher start [--port <port>]

Option	Default	Description
-p, --port <port>	5050	Port to listen on. A whole number from 1 to 65535.
-h, --help		Show help for the command.

There is no option to change the host. Watcher always listens on 127.0.0.1.

Output

Starting Watcher…
Watcher project root: /path/to/your-project
Discovery: package.json found, 1 Playwright config(s), 1 test directory, 5 package script(s)
Test inventory: 2 spec file(s) across 1 directory
Project health: healthy (0 error(s), 0 warning(s))
Dashboard: http://127.0.0.1:5050
Press Ctrl+C to stop Watcher.

If any health check is not healthy, a line such as warning: <reason> follows the health summary. If run history cannot start, Watcher prints History warning: <reason> and keeps running.

Stopping

Press Ctrl+C. Watcher stops any active managed run or tool session, finishes saving pending history (for up to five seconds), and exits.

Errors

Watcher exits with code 1 and a short message in these cases:

Situation	Message
No package.json in the current directory	No package.json found in <folder>. Run Watcher from your Playwright project root.
Invalid port	Invalid port: <value>. Use a whole number from 1 to 65535.
Port in use	Port <port> is already in use. Try: npx watcher start --port <another-port>
Unsupported Node.js	Watcher requires Node.js ^22.13.0 || >=24.0.0.

When it refuses to start in a folder without package.json, Watcher writes nothing to disk.

watcher --version

npx watcher --version

Prints the installed version, for example 0.1.0-alpha.1.

No other commands

The Alpha has no init or configuration command, and no configuration file. Watcher creates .watcher/ automatically on the first valid start.