commentware runs a server and manages its users, projects, sites, settings
and database.
Usage: commentware [options] [command]
The Commentware server. Holds your comments in a database on this machine, and serves them to the browser extension and to AI agents.
-V, --version— output the version number
This page lists version 0.17.0 of the server, the newest release. An entry that names no version it was added in was in version 0.13.0.
Run commentware --version to print the version you have. Every command
takes -h, --help, which prints what your version’s command takes, and a
command that holds others also takes help [command].
init
Usage: commentware init [options]
Write a commentware.config.json giving this directory its own comments.
-g, --global— write this user's own config instead, reached from every directory-p, --port <port>— port the server will bind-n, --name <name>— how the server introduces itself to clients--force— replace a config file that is already there
start
Usage: commentware start [options]
Start the server.
-p, --port <port>— port to bind (default: 7042)-H, --host <host>— interface to bind; anything but loopback is reachable from outside this machine (default: 127.0.0.1)-n, --name <name>— how this server introduces itself to clients (default: Commentware)--public-origin <origin>— address clients reach this server at, when a proxy answers for it (default: the address it binds)--config <path>— commentware.config.json to use; the default searches upward from this directory--no-setup— take the defaults instead of asking, on a first run--foreground— keep the server in this terminal; at a terminal it runs in the background otherwise
stop
Usage: commentware stop [options]
Stop the server the commands in this directory address, once it has finished what it is doing.
--all— stop every server running on this machine for this user, the onescommentware serverslists--config <path>— commentware.config.json to use; the default searches upward from this directory
restart
Usage: commentware restart [options]
Restart the server the commands in this directory address, with the arguments and working directory it was started with.
--config <path>— commentware.config.json to use; the default searches upward from this directory
logs
Usage: commentware logs [options]
Print what this directory's background server wrote to its log.
--config <path>— commentware.config.json to use; the default searches upward from this directory-n, --lines <count>— how many lines from the end (default: 50)-f, --follow— keep printing what it writes, until interrupted
servers
Usage: commentware servers [options]
List every Commentware server running on this machine, wherever it was started.
service
Usage: commentware service [options] [command]
Run this directory's server under systemd (Linux) or launchd (macOS): at login, and again after a crash.
service install
Usage: commentware service install [options]
Install the server as a service and start it.
--config <path>— commentware.config.json to use; the default searches upward from this directory
service uninstall
Usage: commentware service uninstall [options]
Stop the service and remove it.
--all— remove every Commentware service installed for this user, whichever database each is for--config <path>— commentware.config.json to use; the default searches upward from this directory
where
Usage: commentware where [options]
Print which database, blobs and port the commands in this directory address.
--json— print the report as JSON, for a program to read, and nothing else--config <path>— commentware.config.json to use; the default searches upward from this directory
mcp
Usage: commentware mcp [options] [command]
Print how to point an AI agent at this server's MCP endpoint. Starts nothing.
--config <path>— commentware.config.json to use; the default searches upward from this directory-p, --port <port>— port to write into the printed URL; defaults to the port the running server bound-H, --host <host>— host to write into the printed URL; defaults to the interface the running server bound--client <id>— print only this client's lines: claude-code, codex, opencode, gemini-cli, vscode or cursor--entry <name>— the entry's name in each client's config, so a second server's entry does not replace the first's; defaults to "commentware". Added in 0.16.0.--json— print the same facts as JSON, for a caller that is not a person
mcp clients
Usage: commentware mcp clients [options] · Added in: 0.16.0
List the MCP clients this machine has and which are connected to this server. Never prints a key.
--config <path>— commentware.config.json to use; the default searches upward from this directory--json— print the same facts as JSON, for a program to read
mcp connect
Usage: commentware mcp connect [options] <client> · Added in: 0.16.0
Give an MCP client a user of its own and write its key into the client's config. Loopback servers only.
--config <path>— commentware.config.json to use; the default searches upward from this directory-p, --port <port>— port of the address written into the client's config; defaults to the port the running server bound-H, --host <host>— host of the address written into the client's config; defaults to the interface the running server bound--entry <name>— the entry's name in the client's config; defaults to the name this server's entry already has, else "commentware"--replace— replace an entry of that name this server did not write, such as another server's, or a browser sign-in to this one--json— print what was done as JSON, for a program to read
mcp disconnect
Usage: commentware mcp disconnect [options] [client] · Added in: 0.16.0
Take this server's entry out of an MCP client's config and revoke its key. The client's user stays.
--config <path>— commentware.config.json to use; the default searches upward from this directory--all— every client on this machine that this server connected--json— print what was done as JSON, for a program to read
purge
Usage: commentware purge [options]
Delete resolved threads past the retention window, end idle reviews, and remove the files only they held.
--config <path>— commentware.config.json to use; the default searches upward from this directory--dry-run— print what would be deleted and delete nothing
db
Usage: commentware db [options] [command]
Look after the database this server keeps your comments in.
db restore
Usage: commentware db restore [options]
Put the pre-migration backup back, database and screenshots.
--config <path>— commentware.config.json to use; the default searches upward from this directory-y, --yes— do not ask for confirmation
projects
Usage: commentware projects [options] [command]
The groupings this server keeps comments apart in.
projects list
Usage: commentware projects list [options]
Every project and what it holds.
--config <path>— commentware.config.json to use; the default searches upward from this directory
projects new
Usage: commentware projects new [options] <name>
Create an empty project.
--config <path>— commentware.config.json to use; the default searches upward from this directory
projects rename
Usage: commentware projects rename [options] <id> <name>
Rename a project.
--config <path>— commentware.config.json to use; the default searches upward from this directory
projects patterns
Usage: commentware projects patterns [options] <id> [action] [pattern]
List the addresses a project claims, or add or remove one: acme.com, *.acme.com, localhost:5173, acme.com/admin.
--config <path>— commentware.config.json to use; the default searches upward from this directory
projects delete
Usage: commentware projects delete [options] <id>
Delete a project, if it holds no sites.
--config <path>— commentware.config.json to use; the default searches upward from this directory
sites
Usage: commentware sites [options] [command]
The domains this server holds comments on.
sites list
Usage: commentware sites list [options]
Every site, and whether screenshots are on for it.
--config <path>— commentware.config.json to use; the default searches upward from this directory
sites screenshots
Usage: commentware sites screenshots [options] <domain> <on|off>
Stop capturing screenshots for one site, or follow the server again.
--config <path>— commentware.config.json to use; the default searches upward from this directory--project <id-or-name>— which project's copy of the domain; needed only when it is in more than one
users
Usage: commentware users [options] [command]
Manage the people and agents that can reach this server.
users list
Usage: commentware users list [options]
List users. Never prints an access key.
--config <path>— commentware.config.json to use; the default searches upward from this directory
users new
Usage: commentware users new [options] [name]
Create a user and print their connection string.
--config <path>— commentware.config.json to use; the default searches upward from this directory-p, --port <port>— port to write into the printed connection string; defaults to the port the running server bound-H, --host <host>— host to write into the printed connection string; defaults to the interface the running server bound--permissions <list>— comma-separated, from can_admin and can_collaborate; asks when left off. "" is a key that may do nothing
users permissions
Usage: commentware users permissions [options] <id> [list]
Set what a user's key may do (can_admin, can_collaborate); asks when the list is left off.
--config <path>— commentware.config.json to use; the default searches upward from this directory
users edit
Usage: commentware users edit [options] <id> <name>
Rename a user. Mentions follow the id, so they are unaffected.
--config <path>— commentware.config.json to use; the default searches upward from this directory
users delete
Usage: commentware users delete [options] <id>
Delete a user and every access key they hold.
--config <path>— commentware.config.json to use; the default searches upward from this directory
users generate
Usage: commentware users generate [options] <id>
Mint another access key for a user and print their connection string. Leaves their other keys working.
--config <path>— commentware.config.json to use; the default searches upward from this directory-p, --port <port>— port to write into the printed connection string; defaults to the port the running server bound-H, --host <host>— host to write into the printed connection string; defaults to the interface the running server bound-n, --name <name>— what to call this key, unique per user; defaults to the next "key-N"--json— print the key and its connection string as JSON, for a program to read, and nothing else
users keys
Usage: commentware users keys [options] <id>
List the access keys a user holds, by name and date. Never prints a key.
--config <path>— commentware.config.json to use; the default searches upward from this directory
users revoke
Usage: commentware users revoke [options] <id> <name>
Revoke one named access key, and every agent that user authorized.
--config <path>— commentware.config.json to use; the default searches upward from this directory
users clear
Usage: commentware users clear [options] <id>
Revoke every access key a user holds, and every agent they authorized.
--config <path>— commentware.config.json to use; the default searches upward from this directory
settings
Usage: commentware settings [options] [command]
Read and write this server's configuration.
settings list
Usage: commentware settings list [options]
Show every setting, its value, and where this shell finds that value.
--config <path>— commentware.config.json to use; the default searches upward from this directory
settings set
Usage: commentware settings set [options] <key> <value>
Store a setting. Beats the environment variable.
--config <path>— commentware.config.json to use; the default searches upward from this directory
settings unset
Usage: commentware settings unset [options] <key>
Forget a stored setting, restoring the environment or default.
--config <path>— commentware.config.json to use; the default searches upward from this directory