Command library

This page centralizes command surfaces that operators and advanced integrators use most.

Scope

Server startup and lifecycle CLI flags
Replay command usage
Runtime operation families worth documenting for operators and advanced integrators

Server CLI flags

`--store <path>`

Enables durable SQLite + blob persistence rooted at path.

`--metrics-addr <ip:port>`

Starts metrics listener with Prometheus endpoint at /metrics.

`--idle-timeout <seconds>`

Idle-room eviction threshold. 0 disables eviction. Durable persistence is required for safe eviction.

`--broadcast-capacity <N>`

Room broadcast channel capacity.

`--peer-rate-nodes <N>`

Per-peer inbound node rate limit (nodes/second). 0 disables node limiter.

`--peer-rate-bytes <MiB>`

Per-peer inbound decoded-pack byte rate limit (MiB/second). 0 disables byte limiter.

`--blob-gc-interval <seconds>`

Blob garbage-collection sweep interval. 0 disables sweeper.

`--blob-gc-grace <seconds>`

Grace period before blob deletion after dereference.

`--snapshot-interval <N>`

Snapshot sweeper trigger interval by node count. 0 disables.

`--snapshot-max-chain <K>`

Max incremental snapshot chain depth before full snapshot fallback.

Replay command

`nodalmerge-server replay <pack-file|->`

Reads base64-encoded postcard pack input, replays, and prints resolved state plus canonical hash. Optional policy timeline inputs:

--policy-timeline <json-file>
--policy-timeline-json '<json>'

Timeline flags are mutually exclusive.

Token minting

`nodalmerge token mint`

nodalmerge token mint \
  --room <room-id> \
  --room-key-seed-hex <64-hex-chars> \
  --peer-seed-hex <64-hex-chars> \
  --caps <comma-separated-list> \
  --ttl-secs <seconds, default 3600>

Signs a room-capability token entirely offline — this is a local RoomToken::sign call with no server round-trip, so the room key seed never leaves the CLI invocation. Useful for scripting locked-room access without standing up a token-minting bridge service. Output (NODALMERGE_TOKEN_JSON shape):

{
  "peer_pubkey": "<hex>",
  "expiry": 1735689600,
  "caps": ["query.read", "archive.read"],
  "sig": "<hex>"
}

Export the output as NODALMERGE_TOKEN_JSON for CLI/SDK calls that require a locked-room token (for example --token-json on other nodalmerge query/replay subcommands). See operators/security-and-auth for capability scope guidance — prefer least-privilege --caps and short --ttl-secs for scripted/CI use.

WebSocket control-plane command families

The following command families are invoked over WebSocket and are capability-gated:

archive: archive.describe, archive.validate, archive.import, archive.export
query/projection: query.register, projection.build, projection.read, projection.invalidate, projection.list
replay query: replay.read-range
topology: topology.create-child, topology.describe-lineage, topology.list-children, topology.propose-promotion, topology.validate-promotion, topology.apply-promotion
room/policy/tick admin: set-room-key, set-policy, start-tick, stop-tick, compact-room

Full runtime command inventory snapshot

Client-routed WebSocket commands currently recognized:

subscribe
pack
request
mst-request
mst-done
blob-upload
blob-request
request-upload
blob-uploaded
presence
set-room-key
set-policy
server-info
start-tick
stop-tick
compact-room
archive.describe
archive.validate
archive.import
archive.export
query.register
projection.build
projection.read
projection.invalidate
projection.list
replay.read-range
topology.create-child
topology.describe-lineage
topology.list-children
topology.propose-promotion
topology.validate-promotion
topology.apply-promotion
webrtc-offer
webrtc-answer
webrtc-ice

Operator-facing CLI/runtime commands currently documented:

nodalmerge-server startup with flags listed on this page
nodalmerge-server replay <pack-file|->
--policy-timeline <json-file>
--policy-timeline-json '<json>'

For command payload schemas and success/reject envelopes, see api-reference/websocket-commands.

​Command library

​Scope

​Server CLI flags

​--store <path>

​--metrics-addr <ip:port>

​--idle-timeout <seconds>

​--broadcast-capacity <N>

​--peer-rate-nodes <N>

​--peer-rate-bytes <MiB>

​--blob-gc-interval <seconds>

​--blob-gc-grace <seconds>

​--snapshot-interval <N>

​--snapshot-max-chain <K>

​Replay command

​nodalmerge-server replay <pack-file|->

​Token minting

​nodalmerge token mint

​WebSocket control-plane command families

​Full runtime command inventory snapshot

​Related pages