feat(cli): meshbay-cli, a command-line client for members

Signs in to the hub, lists the account's groups and their folders, and
downloads and uploads files directly with each group's node, end-to-end
encrypted. With no argument it opens a two-pane interactive mode (Textual).
Session and device keys are kept encrypted under the system's key storage,
or a 0600 key file where there is none; node keys are pinned at first
contact; a new machine links as a device.

Packaged on its own on Linux (deb and rpm, on meshbay-common's venv, with a
man page generated from the parser) and frozen next to meshbay-node in the
full Windows installer, not the light one, with a self-test the build runs.
client/keys.py ports keyderive.js and is LGPL like it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 39 insertions, 0 deletions

diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index bab2074..1c21c80 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -224,6 +224,43 @@ points the node at another account. A folder you pick in the folder dialog is no
 twice. That window belongs to the application, so nothing displayed in the page
 — which shows content from other people's nodes — can answer it for you.
 
+### The command-line client
+
+`meshbay-cli` reaches your groups' files from a terminal — a server, a script, a
+machine with no desktop. It is a package of its own on Linux (`meshbay-cli`,
+with a manual page: `man meshbay-cli`), and comes with the desktop
+application's full installer on Windows (not with the light one).
+
+```bash
+meshbay-cli login -u alice              # asks for the passphrase
+meshbay-cli groups                      # your groups, their node, your role
+meshbay-cli ls -l Family/photos         # a group, a folder of it
+meshbay-cli get -R Family/photos/2024   # download, here; -o elsewhere
+meshbay-cli put -R ~/scans Family/documents
+meshbay-cli logout
+```
+
+A group is named as the GROUP column of `meshbay-cli groups` prints it; add
+`@owner` only when two of your groups share a name. Quote wildcards
+(`'Family/music/*.flac'`): they are matched against the group, not against
+your disk. An interrupted download resumes where it stopped the next time you
+run the same `get`. Run `meshbay-cli` with nothing after it for a two-pane
+view: this computer on the left, your groups on the right, F5 to copy the
+selection across.
+
+`login` remembers the session, so later runs need no passphrase; `logout`
+forgets it and everything else stored on this computer. What is kept is
+encrypted, under a key held by the system's key storage — or, on a machine
+that has none (a server with no desktop session), in a file only your user
+can read, which `login` tells you.
+
+The first time it opens a group, the client may print a linking code instead
+of the files: the node holds no copy of your keys (Browser access is off), so
+this computer asks to be added as one of your devices. Enter the code in the
+application under *Your devices on this node*; the client goes on by itself.
+
+Managing a node is not the client's job: that is `meshbay-node` (§6).
+
 ---
 
 ## 4. Joining a group
@@ -1198,6 +1235,8 @@ Better to know now than to go looking for it:
   phones take JPEG unless set otherwise.
 - **Hubs do not talk to each other yet.** Everyone in a group needs an account
   on the same hub.
+- **The command-line client lists, downloads and uploads.** Searching across
+  groups and chat are not in it yet.
 - **Casting reaches Chromecast devices** from the desktop and Android
   applications, for films, photos and music. Support for other TV protocols is
   designed but not built.