====== cli.py ======

The RobinNet CLI is the primary operator tool for managing a local node.

It provides commands for:

  * initializing a node
  * inspecting node information
  * adding and removing peers
  * testing peer connectivity
  * 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.

-----

===== General Usage =====

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 \
  init-node \
  --name alpha \
  --operator "Rich" \
  --callsign N2XYZ \
  --location "Albany area"
</code>

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>
python -m robinnet.cli \
  --db ./data/node.db \
  add-peer \
  --name bravo \
  --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