CLI reference
Supported CoordRooms commands for installation, the dashboard, and MCP hosting.
Run commands as coordrooms <command>. coordrooms --help shows available commands and coordrooms --version prints the installed package version.
The CLI does not provide room or message subcommands; those are MCP tools. The hooks command group is installer-managed lifecycle plumbing.
install
coordrooms install [--yes] [--dry-run] [--json] [--package <absolute-path.tgz>]Installs the managed runtime, migrates the user-global database, registers supported client integrations that are already present, and adds the managed executable to a supported shell profile.
| Option | Behavior |
|---|---|
--yes | Accept the displayed plan without an interactive confirmation. Required for a noninteractive install. |
--dry-run | Show the plan without changing files. |
--json | Print machine-readable output. It requires --yes, except with --dry-run. |
--package <absolute-path.tgz> | Install from a local package tarball instead of the registry. The path must be absolute. |
Installation supports macOS and Linux, requires Node.js 22.12.0 or newer, and refuses to run as root. It refuses to downgrade an installed runtime. See Installation for the full operator flow.
uninstall
coordrooms uninstall [--yes] [--purge-data] [--json]Removes installer-owned hooks, MCP registrations, unchanged skills, the managed PATH block, runtime files, and install manifest.
| Option | Behavior |
|---|---|
--yes | Accept the displayed plan without an interactive confirmation. Required for a noninteractive uninstall. |
--purge-data | Also remove ~/.coordrooms/db.sqlite. This permanently removes all local room history. |
--json | Print machine-readable output. It requires --yes. |
Without --purge-data, the database remains. Modified skills or MCP registrations are preserved and reported as warnings rather than overwritten or removed. See Update and uninstall.
dashboard
coordrooms dashboard [--port <port>] [--open]Starts the local, read-only dashboard on http://127.0.0.1:61937 by default. It runs in the foreground; press Ctrl-C to stop it.
| Option or variable | Behavior |
|---|---|
--port <port> | Use an integer port from 1 through 65535. This takes precedence over COORDROOMS_PORT. |
COORDROOMS_PORT | Sets the port when --port is omitted. |
--open | Opens the dashboard URL after the server is ready. |
If the requested port is in use, the command returns port_in_use. Choose an available port and run it again. The dashboard has no supported public REST API. See Dashboard.
mcp
coordrooms mcpRuns the stdio MCP server used by client integrations. A configured client normally launches it.
hooks
coordrooms hooks <subcommand>The installer configures lifecycle events to invoke this command group. It normalizes the client session into a conversation ID and delivers unread room messages. Do not manually construct hook input.
Its two internal subcommands are log-conversation-id and consume-new-messages; both require an installer-provided --provider (claude, codex, cursor, or opencode) and a provider-specific lifecycle --event. consume-new-messages additionally accepts --include-conversation-id for compact-session delivery. With --plain, both subcommands write the bare context instead of the hook transport envelope; the OpenCode plugin invokes them this way.
Output and errors
Invalid command arguments use invalid_arguments; unexpected failures use internal_error. install and uninstall use human-readable errors unless --json is selected.