Skip to content

Command line interface

The cumments binary doubles as a local administration CLI. It operates directly on the same SQLite database the server uses, so whoever can read and write the database is an operator — there is no separate operator token on the CLI path. Use the Operator HTTP API when managing a remote instance.

The CLI mirrors the Operator API: anything the Operator API can do, the CLI can do locally.

Global flags

  • --config <path> (also -c): configuration file. The flag is global, so it can appear before or after a subcommand:

bash cumments --config cumments.toml sites list cumments sites list --config cumments.toml

  • --help, --version.

Command tree

cumments
├── appservice
│   └── generate-registration [--url ...] [--server-name ...] [--output FILE]
├── backfill [--max-pages N]
├── backup --output FILE
├── audit [--actor MXID] [--limit N]
├── sites
│   ├── register [--site-id ID]
│   ├── list [--site-id ID] [--page N] [--per-page N] [--table]
│   ├── revoke-origin SITE_ID ORIGIN
│   ├── rotate-secret SITE_ID
│   ├── revoke-secret SITE_ID --yes
│   ├── export-config [--raw] SITE_ID
│   ├── rotate-claim-token SITE_ID
│   ├── add-admin SITE_ID USER_ID
│   ├── remove-admin SITE_ID USER_ID
│   ├── add-manager SITE_ID USER_ID
│   ├── remove-manager SITE_ID USER_ID
│   ├── transfer-owner SITE_ID USER_ID
│   └── retire SITE_ID --yes [--wait]
├── rooms
│   ├── list-quarantined [--site-id ID] [--page N] [--per-page N] [--table]
│   ├── reinstate ROOM_ID
│   └── upgrade ROOM_ID VERSION
│   └── retire ROOM_ID --yes [--wait]
└── completions SHELL

Output conventions

  • Machine-readable data (site lists, quarantined rooms, secrets, tokens) goes to stdout as JSON, matching the Operator API response shape. --table on list commands switches to a human-readable table.
  • Human notes and warnings go to stderr, so stdout stays script-friendly.
  • Secrets and claim tokens are printed exactly once; the CLI refuses to show them again.
  • export-config prints the {"site_id","toml"} wrapper returned by the Operator API; --raw prints only the TOML block for shell redirection.
  • rooms reinstate prints {"room_id","status":"active"}. This is a CLI-side enhancement of the Operator API, which returns an empty 204: the CLI has no body-free "no content" convention, so it reports the affected resource.
  • rooms upgrade prints {"room_id","new_version","replacement_room"}, matching the Operator API response.
  • rooms retire prints {"room_id","status":"retiring"} (or "retired" after --wait completes), matching the Operator API response shape.
  • Exit codes: 0 success, 1 runtime error, 2 usage error (clap).

Examples

List managed sites (database rows merged with the [sites] overlay):

cumments sites list
cumments sites list --site-id my-blog --table

List quarantined rooms and reinstate one:

cumments rooms list-quarantined
cumments rooms reinstate '!ps4zwsSTsR6qph4L8Yqi5j6wfALV1-EIY5cI1TCq8DE'

Upgrade a comment room (the target version must be newer than the room's current version, e.g. upgrading a v11 room to 12):

cumments rooms upgrade '!ps4zwsSTsR6qph4L8Yqi5j6wfALV1-EIY5cI1TCq8DE' 12

List the chat command audit log (newest first), optionally filtered by actor:

cumments audit
cumments audit --actor '@alice:example.com' --limit 20

Rotate a site's HMAC secret (printed once) or revoke it (destructive, needs --yes):

cumments sites rotate-secret my-blog
cumments sites revoke-secret my-blog --yes

Export a TOML block to move a database-tracked site into declarative configuration:

cumments sites export-config my-blog
cumments sites export-config --raw my-blog >> cumments.toml

Register or revoke a site-level role. Both add-* commands store a pending claim and print the one-time verify_token; the target Matrix account must DM cumments-claim:<token> to the AS bot before the role is applied. The CLI never writes Matrix power levels directly:

cumments sites add-admin my-blog '@alice:example.com'
cumments sites remove-admin my-blog '@alice:example.com'
cumments sites add-manager my-blog '@bob:example.com'
cumments sites transfer-owner my-blog '@carol:example.com'

remove-* cancels a pending claim; a role that has already been applied is removed from the Space power levels directly. In matrix.mode = "logging" there is no real homeserver, so the local claim row is updated but Matrix state is not actually changed.

Retire a site (destructive, needs --yes). The command marks the site retiring — writes stop immediately — and the running server's background reconciler retires its Matrix Space and rooms, then clears the local data. Without --wait the command returns once the site is marked; with --wait it polls until the retirement finishes (or times out after five minutes). Config-declared sites cannot be retired; remove them from the config file instead.

cumments sites retire my-blog --yes
cumments sites retire my-blog --yes --wait

Shell completions

Generate a completion script and source it from your shell profile:

cumments completions bash   # or zsh / fish / powershell

For example, with bash:

cumments completions bash > ~/.local/share/bash-completion/completions/cumments

Safety

  • sites revoke-secret requires --yes because it removes a credential and changes the site's write path.
  • backup --output refuses to overwrite an existing file.
  • Origins and secrets declared in [sites] cannot be changed through the CLI (or the Operator API): edit the configuration file instead.