Hub commands for Mobile & Bridge

Phones and bridges are administered from the hub machine with the c3sync CLI. This page covers the mobile-relevant surface; the full hub reference (init, run, export/import, C3Sync devices) lives in the C3Sync CLI docs.

Identity management — c3sync hub control …

enroll-phone --name "<name>" [--out <file>]

Mint a phone identity and print its enrollment QR to the terminal. The QR carries the hub's WSS address, CA pin, and a short-lived enrollment secret — treat it as a secret while valid. --out additionally writes the payload to a file (for enrolling without a shared screen; guard it accordingly).

enroll-bridge --name "<name>" --host-id <id> [--out bridge.json]

Mint a bridge enrollment bundle for one host. --host-id is the stable identity the host presents everywhere (Signal map, sessions list); pick something you'll recognize. Import it on the host with c3bridge init --bundle.

devices

List every phone and bridge identity the hub has minted, with kind, ID, name, public key, and status. This is where you find the USER_PUB for a revocation.

revoke <USER_PUB>

Revoke a phone or bridge at the hub: its NATS credential is invalidated and a signed, monotonic revocation manifest tells every bridge to drop related pair state on next connection. Effective even while the revoked device is offline.

status

Show any interrupted control revocation and the signed manifest's current epoch. Check this before starting another administration operation after a crash or power loss.

recover-revocation <USER_PUB>

Resume the exact pending revocation reported by status. The identity must match the durable intent; the command will not substitute another device.

abort-revocation <USER_PUB> --confirm-abort-unapplied

Remove a pending intent only if neither the control account nor device registry has applied it. The bridge refuses an unsafe abort.

rebuild-revocations --next-epoch <n> --confirm-replace-invalid

Replace an invalid signed manifest from the validated device registry. The epoch must exceed every epoch previously accepted by a phone or bridge; the invalid file is retained as a private recovery copy.

enrollments [--json] and enrollments cancel <ENROLLMENT_ID>

Inspect pending, expired, and recently consumed phone offers, or cancel one exact unconsumed offer.

backup --out <file>

Export the hub's administration keys, sealed under a passphrase you choose. Re-run after every revocation or TLS ceremony. Store offline, separate from the passphrase.

Certificate lifecycle — c3sync hub tls …

renew-leaf

Routine renewal: rotate the hub's serving certificate under the same CA. The pin doesn't change — phones, bridges, and C3Sync devices keep working. Verifies the pin is unchanged and reloads the hub in place.

rotate-ca --confirm-re-enroll-all

The nuclear option, for suspected CA compromise: replaces the CA and the entire control account, clears device and enrollment registries, and disconnects every phone and bridge. Everything must re-enroll and re-pair, which is why the confirmation flag is mandatory.

Recovery ceremonies

Lost phone

1. c3sync hub control devices — find the phone's USER_PUB.
2. c3sync hub control revoke <USER_PUB>.
3. Run c3sync hub control status; recover the exact revocation if an interruption left it pending.
4. Confirm it's disconnected; bridges shed its pair state on their next connection.
5. Take a fresh hub control backup.
6. If the phone turns up again: Settings → Remove hub on it, then re-enroll cleanly.

Lost or retired bridge

Revoke its USER_PUB at the hub. When retiring a healthy host, also c3bridge service uninstall and delete ~/.c3bridge. Pair state is not transferable — a replacement bridge install pairs fresh.

Lost hub administrator

c3sync hub restore --in c3-hub-backup.sealed --dir ~/.c3sync/hub

Restores hub administration from a sealed backup onto a (new) machine. Deliberately disruptive: it rotates the CA and control account, so every phone and bridge re-enrolls and re-pairs afterwards. Take a new backup immediately and retire the old one. (C3Sync device enrollment is separate and has its own recovery story — see the C3Sync security model.)

NOTE — > Control enrollment, revocation, recovery, backup, and TLS commands run on the hub machine (or wherever the administration keystore lives after a restore), because they need the hub's signing keys.