diff options
Diffstat (limited to 'docs/USERGUIDE.md')
| -rw-r--r-- | docs/USERGUIDE.md | 134 |
1 files changed, 112 insertions, 22 deletions
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index bab2074..1808598 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -212,10 +212,14 @@ a browser can open your groups with your passphrase. With it off — the default an account created in the application — your keys stay on this computer and nothing of them is left on anybody's node. With it on, the application leaves a locked copy on each node, as a browser would. The change reaches each group the -next time it opens. A browser can also be approved from the application for -itself, group by group: the browser shows a linking code (*Get a linking code*), -and you enter it in the application under *Your devices on this node*. That gives -the browser keys of its own without turning browser access on. +next time it opens. With it off, only the application (and the command-line +client) opens your groups: a browser keeps no keys between visits, so it cannot be +linked as a device of its own. + +On another computer, the application opens a group with keys of its own once a +device already linked approves it: the group shows a linking code (*Get a linking +code*), you enter it on that device under *Your devices on this node*, and the +group opens by itself. The application asks in a small window of its own, not in the page, before it hosts a group on this computer, shares a folder you did not pick in its folder @@ -224,6 +228,101 @@ 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 and their 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 search beach 2024 # every group at once; paths get takes +meshbay-cli chat Family # the last 10 messages; -100 for 100 +meshbay-cli chat Family -m "On my way" # post one (-m - reads it from stdin) +meshbay-cli chat Family --follow # then each new message, until Ctrl+C +meshbay-cli chat # interactive: pick a group, talk, Esc to leave +meshbay-cli get -R Family/photos/2024 # download, here; -o elsewhere +meshbay-cli stream --player vlc 'Family/films/Night Drive.mkv' # play it; Ctrl+C stops +meshbay-cli put -R ~/scans Family/documents +meshbay-cli rm Family/documents/old-draft.odt # asks first; --yes in a script +meshbay-cli mkdir --parents Family/documents/2026/taxes +meshbay-cli rm -r Family/documents/2019 # a folder and all it holds +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`. `stream` plays a film or a song without downloading it: +it prints an address to open in VLC or mpv (or starts the player with +`--player`), which works on this computer only and until you press Ctrl+C or +close the player; skipping ahead in the player works. `rm` deletes what you uploaded, from any of your devices; +the node's operator can delete anything, and only the operator removes a +folder (`rm -r`, which says how many files go before it asks). 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, Delete to delete it from the group (what `rm` may delete). + +`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*, or run +`meshbay-cli devices approve GROUP CODE` on a computer already linked; the +client goes on by itself. + +Joining and leaving work as in the application (§4): + +```bash +meshbay-cli invitations # what you were invited to +meshbay-cli join Family@bob --code K7P2-9WQX # accept, then give the node its code +meshbay-cli join 'https://meshbay.org/#/invite?v=1&...' # a link, pasted as sent +meshbay-cli decline Club@carol +meshbay-cli leave Club@carol # asks first; --yes in a script +``` + +`meshbay-cli devices list GROUP` shows your devices on the node serving a group; +`devices approve` admits a new one by its code, `devices revoke` retires one. + +Like the application, the client keeps your keys to itself: a browser cannot +open, with your passphrase alone, a group you joined from it. To allow that, as +*Browser access* does in the application, run `meshbay-cli browser-access on` +on that computer; `off` takes the copy back. It is that computer's setting. + +Your account, from the client: + +```bash +meshbay-cli account # name, e-mail address, status +meshbay-cli account register -u alice --email alice@example.org +meshbay-cli account passphrase # change it; asks the current one, then the new +meshbay-cli account reset -u alice --email alice@example.org # forgotten: a code by e-mail +meshbay-cli account email new@example.org +meshbay-cli account sign-out-everywhere +meshbay-cli account delete +``` + +`register` prints your recovery key once: keep it apart from your passphrase, +it is what gives your groups back after a `reset`. Changing the passphrase +carries the copy of your keys each node keeps for browsers over to the new one +first; a node out of reach is carried the next time this computer connects to it. + +Tab completes actions, options and the paths in your groups once the shell +knows how. In bash, add `eval "$(meshbay-cli completion bash)"` to `~/.bashrc` +(the Linux packages install it already); in PowerShell, add +`meshbay-cli completion powershell | Out-String | Invoke-Expression` to your +`$PROFILE`. It never asks for anything: on a computer that is not signed in, +it completes actions and options only. + +Managing a node is not the client's job: that is `meshbay-node` (§6). + --- ## 4. Joining a group @@ -389,8 +488,8 @@ that matters to you. ### Backing up your phone On the Android application, **Android Sync** in the menu under your avatar, -top right, backs up your phone's photos, contacts, calendar, text messages and -the files of folders you choose to a group. +top right, backs up your phone's photos, contacts, calendar and the files of +folders you choose to a group. Text messages are not backed up. Only your **personal profile** is backed up. If your phone has a work profile, nothing in it is sent, and MeshBay installed inside the work profile offers no @@ -455,18 +554,6 @@ backup at all. (`calendar-2026-10-10-0900.ics`). Any calendar application can import it; repeating events, their exceptions and reminders come along. -#### Text messages - -- **Turn on** asks for access to your text messages. The first copy holds them - all; then, once a day, a new file holds only the ones that arrived or were - sent since. -- The files go by year (`alice-messages/2026/sms-2026-10-10-0900.xml`), in the - XML format SMS backup applications can restore onto a phone. Senders are - named when contacts backup is also allowed. Multimedia messages (MMS) are - not included. -- The version of the application from the Play Store has no text messages - backup: Play allows reading them only to the phone's messaging application. - #### Files - **Add a folder** opens Android's folder picker: choose `Documents`, a folder @@ -1001,9 +1088,10 @@ anything missing. **"No nodes are currently online for this group."** The node is not running, is not reachable, or has not linked its key to the hub. On the node: `meshbay-node status`, then Step 4 and 5 of the quickstart. -In the desktop app, the **Node** page says when your account is linked to the -node of another machine (**Link this node instead**); **Profile → Unlink** -lets go of a node from anywhere, for a machine that is gone. +In the desktop app, the **Node** page says when this machine's node is not +linked to your account (**Link this node**). **Profile → Linked nodes** lists +every node your account has linked, one per machine, and **Unlink** lets go of +one from anywhere — for a machine that is gone — without touching the others. **A member sees the group but no files.** They never redeemed an invitation code, or the group has no key @@ -1034,7 +1122,7 @@ fresh invitation code. **"Browser access is off for this account."** The account keeps its keys in the desktop application. Turn browser access on -there (Profile), or approve this browser from it. +there (Profile). **Video says the codec is not supported.** The source codec has no decoder in that browser and transcoding is off, or @@ -1198,6 +1286,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. |