Skip to main content

​
Command library

This page centralizes command surfaces that operators and advanced integrators use most. It is seeded from nodalmerge/docs/operations-inventory.md and server runtime code.

​
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.

​
Planned expansion areas

  • Environment variable catalog (with defaults and precedence)
  • Capability and auth-related runtime toggles
  • Archive/query/topology operator workflows with example payloads
  • Deprecation and migration notes per command/flag

​
Command entry template

For each command or flag, include:
  1. Status (stable, experimental, deprecated)
  2. Purpose
  3. Accepted values and defaults
  4. Side effects and safety notes
  5. Metrics/logs to observe
  6. Version-introduced and version-changed metadata