Differences

This shows you the differences between two versions of the page.

--- robinnet:cli [2026/03/11 15:28] – created freedomotter
+++ robinnet:cli [2026/03/11 15:45] (current) – freedomotter
@@ Line 1: / Line 1: @@
 ====== cli.py ======
-Command line interface for RobinNet node management.
+The RobinNet CLI is the primary operator tool for managing a local node.
-This tool allows operators to:
+It provides commands for:
-  * initialize nodes
+  * initializing a node
-  * manage peers
+  * inspecting node information
-  * post messages
+  * adding and removing peers
-  * trigger sync operations
+  * testing peer connectivity
-  * inspect database state
+  * posting bulletins
+  * listing and viewing messages
+  * viewing message trace history
+  * syncing one peer or all peers
+  * expiring old messages
+  * generating test data
+The CLI is designed to be the main operational interface before the future Cardinal UI.
 -----
-===== Example =====
+===== General Usage =====
-List messages:
+RobinNet commands are run as a Python module.
+Basic format:
+<code bash>
+python -m robinnet.cli --db ./data/node.db <command> [options]
+</code>
+Example:
+<code bash>
+python -m robinnet.cli --db ./data/node.db node-info
+</code>
+-----
+===== Node Commands =====
+==== init-node ====
+Initializes or updates the local node identity.
+Example:
 <code bash>
 python -m robinnet.cli \
   --db ./data/node.db \
-  list-messages
+  init-node \
+  --name alpha \
+  --operator "Rich" \
+  --callsign N2XYZ \
+  --location "Albany area"
 </code>
-Add peer:
+Options:
+  * ''--name'' local node name
+  * ''--operator'' operator name
+  * ''--callsign'' operator callsign
+  * ''--location'' human-readable location
+  * ''--transport-profile'' transport label such as ''lan'', ''mesh'', or ''packet''
+  * ''--node-uuid'' optional explicit UUID
+-----
+==== node-info ====
+Displays the local node record.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  node-info
+</code>
+JSON output:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  node-info \
+  --json
+</code>
+-----
+===== Peer Commands =====
+==== add-peer ====
+Adds or updates a peer node.
+Example:
 <code bash>
@@ Line 32: / Line 105: @@
   --url http://127.0.0.1:8082
 </code>
+Options:
+  * ''--name'' peer display name
+  * ''--url'' peer base URL
+  * ''--transport'' transport label
+  * ''--peer-uuid'' optional peer UUID
+  * ''--notes'' optional notes
+  * ''--disabled'' add the peer as disabled
+-----
+==== list-peers ====
+Lists configured peers.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-peers
+</code>
+Show enabled peers only:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-peers \
+  --enabled-only
+</code>
+JSON output:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-peers \
+  --json
+</code>
+-----
+==== remove-peer ====
+Removes a peer by local peer id.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  remove-peer \
+  --peer-id 1
+</code>
+-----
+==== peer-test ====
+Tests connectivity and identity for one peer.
+This command:
+  * checks the remote health endpoint
+  * fetches the remote node info
+  * updates ''last_seen_at'' if successful
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  peer-test \
+  --peer-id 1
+</code>
+Options:
+  * ''--connect-timeout'' HTTP connect timeout
+  * ''--read-timeout'' HTTP read timeout
+  * ''--json'' JSON output
+JSON output example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  peer-test \
+  --peer-id 1 \
+  --json
+</code>
+-----
+===== Message Commands =====
+==== post-bulletin ====
+Creates a new local bulletin.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  post-bulletin \
+  --title "Water Distribution" \
+  --body "Town Hall from 10:00 to 16:00."
+</code>
+Options:
+  * ''--title'' bulletin title
+  * ''--body'' bulletin body text
+  * ''--author'' optional author override
+  * ''--author-callsign'' optional author callsign override
+  * ''--scope'' ''local'', ''regional'', or ''network''
+  * ''--expires-at'' ISO timestamp
+  * ''--priority'' priority from 0 to 9
+  * ''--local-only'' prevent later export
+  * ''--rf-eligible'' future RF eligibility marker
+Example with more options:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  post-bulletin \
+  --title "Shelter Open" \
+  --body "Community Center open until 22:00." \
+  --scope regional \
+  --priority 5 \
+  --rf-eligible
+</code>
+-----
+==== list-messages ====
+Lists locally stored messages.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-messages
+</code>
+Show message bodies:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-messages \
+  --show-body
+</code>
+Filter by type:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-messages \
+  --msg-type bulletin
+</code>
+Filter by status:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-messages \
+  --status active
+</code>
+JSON output:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  list-messages \
+  --json
+</code>
+-----
+==== show-message ====
+Displays one message by UUID.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  show-message \
+  --msg-uuid 12345678-1234-1234-1234-123456789abc
+</code>
+-----
+==== show-trace ====
+Displays trace history for one message UUID.
+This is useful for following import/export history.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  show-trace \
+  --msg-uuid 12345678-1234-1234-1234-123456789abc
+</code>
+JSON output:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  show-trace \
+  --msg-uuid 12345678-1234-1234-1234-123456789abc \
+  --json
+</code>
+-----
+==== delete-message ====
+Deletes one message by UUID.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  delete-message \
+  --msg-uuid 12345678-1234-1234-1234-123456789abc
+</code>
+-----
+===== Sync Commands =====
+==== sync-peer ====
+Synchronizes one configured peer.
+By default it performs both:
+  * pull from peer
+  * push to peer
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-peer \
+  --peer-id 1
+</code>
+Pull only:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-peer \
+  --peer-id 1 \
+  --pull-only
+</code>
+Push only:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-peer \
+  --peer-id 1 \
+  --push-only
+</code>
+Options:
+  * ''--connect-timeout'' HTTP connect timeout
+  * ''--read-timeout'' HTTP read timeout
+  * ''--pull-limit'' maximum summaries/messages to fetch
+  * ''--push-limit'' maximum push candidates
+  * ''--json'' output structured JSON
+-----
+==== sync-all ====
+Synchronizes all enabled peers.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-all
+</code>
+Pull only:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-all \
+  --pull-only
+</code>
+Push only:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-all \
+  --push-only
+</code>
+JSON output:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  sync-all \
+  --json
+</code>
+-----
+===== Maintenance Commands =====
+==== expire-messages ====
+Marks expired messages as ''expired''.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  expire-messages
+</code>
+Show expired messages after the update:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  expire-messages \
+  --show
+</code>
+Show expired messages as JSON:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  expire-messages \
+  --show \
+  --json
+</code>
+-----
+==== generate-test-data ====
+Creates local test bulletins for development and sync testing.
+Example:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  generate-test-data \
+  --count 5
+</code>
+Custom prefixes:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  generate-test-data \
+  --count 10 \
+  --title-prefix "Test Bulletin" \
+  --body-prefix "Generated message"
+</code>
+Include full message output:
+<code bash>
+python -m robinnet.cli \
+  --db ./data/node.db \
+  generate-test-data \
+  --count 3 \
+  --include-messages \
+  --json
+</code>
+Options:
+  * ''--count'' number of test messages
+  * ''--title-prefix'' title prefix
+  * ''--body-prefix'' body prefix
+  * ''--scope'' ''local'', ''regional'', or ''network''
+  * ''--expires-at'' optional expiration timestamp
+  * ''--priority'' priority from 0 to 9
+  * ''--local-only'' mark generated messages local only
+  * ''--rf-eligible'' mark generated messages RF eligible
+  * ''--include-messages'' include full records in output
+  * ''--json'' JSON output
+-----
+===== Typical Workflow =====
+A basic operator workflow might be:
+  - initialize node
+  - add one or more peers
+  - test peer connectivity
+  - post a bulletin
+  - sync with peers
+  - inspect messages and trace
+Example:
+<code bash>
+python -m robinnet.cli --db ./data/alpha.db init-node --name alpha --operator "Rich"
+python -m robinnet.cli --db ./data/alpha.db add-peer --name bravo --url http://127.0.0.1:8082
+python -m robinnet.cli --db ./data/alpha.db peer-test --peer-id 1
+python -m robinnet.cli --db ./data/alpha.db post-bulletin --title "Test" --body "Hello RobinNet"
+python -m robinnet.cli --db ./data/alpha.db sync-all
+python -m robinnet.cli --db ./data/alpha.db list-messages --show-body
+</code>
+-----
+===== Notes =====
+The CLI is intended to remain fully functional even after Cardinal exists.
+That means:
+  * Cardinal can become a friendly frontend
+  * the CLI remains the operator and sysop tool
+  * automation and scripting remain easy