diff --git a/README.md b/README.md index 6e4e5cc5..35a8165b 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,32 @@ $ beeper accounts add Variants: `beeper install server`, `beeper install server --server-env staging`. +#### Headless server (no browser) + +On a VPS or machine without a graphical environment, use the email-based auth +flow instead of OAuth: + +```text +$ beeper setup --server --install +▎ Installed Beeper Server (stable) +▎ Started server on http://127.0.0.1:23374 + +$ beeper auth email start --email you@example.com -t server + setupRequestID 20260527…-a76ef169-… + +$ beeper auth email response --code 570056 --setup-request-id 20260527…-a76ef169-… -t server --yes +▎ Not ready needs verification + +$ beeper verify recovery-key -t server --key "XXXX-XXXX-XXXX-…" +▎ Ready server + endpoint http://127.0.0.1:23374 + +$ beeper targets enable server +Enabled target at login +``` + +See [setup — Headless server setup](packages/cli/docs/setup.md#headless-server-setup) for details. + ### 3. Remote Desktop or Server via OAuth (PKCE) For a Beeper Desktop or Server running on another machine, authorize the CLI diff --git a/packages/cli/docs/auth.md b/packages/cli/docs/auth.md index dfd1bbff..7804a15a 100644 --- a/packages/cli/docs/auth.md +++ b/packages/cli/docs/auth.md @@ -12,6 +12,8 @@ target file under `~/.beeper/targets/`; `BEEPER_ACCESS_TOKEN` overrides it. ```sh beeper auth status beeper auth logout +beeper auth email start --email # start headless email sign-in +beeper auth email response --code --setup-request-id # finish email sign-in beeper auth verify [--user @id] # interactive happy-path beeper auth verify start [--user @id] # individual steps beeper auth verify status @@ -21,7 +23,7 @@ beeper auth verify sas beeper auth verify sas-confirm beeper auth verify qr-scan --payload beeper auth verify qr-confirm -beeper auth verify recovery-key [--code KEY] +beeper verify recovery-key --key beeper auth verify reset-recovery-key beeper auth verify cancel ``` @@ -30,6 +32,7 @@ beeper auth verify cancel - `auth status` reports the token source (env vs. target file) and metadata; it does not call the network. - `auth logout` revokes the token at the Desktop OAuth endpoint and clears the local copy. +- `auth email start` + `auth email response` provide a two-step email-based sign-in that works without a browser — ideal for headless servers and VPS environments. See [setup — Headless server setup](setup.md#headless-server-setup) for a full walkthrough. - `auth verify` (no subcommand) walks the most common SAS/emoji verification flow interactively. - For agents, drive the explicit subcommands (`start` → `sas` → `sas-confirm`) and use `--json` to inspect state. - `verify status` returns the encryption-readiness state (`ready`, `needs-verification`, `verification-in-progress`). @@ -39,8 +42,10 @@ beeper auth verify cancel ```sh beeper auth status --json +beeper auth email start --email you@example.com -t server +beeper auth email response --code 123456 --setup-request-id -t server --yes beeper auth verify -beeper auth verify recovery-key --code ABCD-EFGH-IJKL-MNOP +beeper verify recovery-key -t server --key "ABCD-EFGH-IJKL-MNOP" beeper auth verify reset-recovery-key beeper auth logout ``` diff --git a/packages/cli/docs/setup.md b/packages/cli/docs/setup.md index 9bf22140..c5d19949 100644 --- a/packages/cli/docs/setup.md +++ b/packages/cli/docs/setup.md @@ -11,7 +11,7 @@ Server / remote targets. ## Commands ```sh -beeper setup [--local | --oauth | --remote URL | --desktop | --server] [--install] [--channel stable|nightly] +beeper setup [--local | --oauth | --email | --remote URL | --desktop | --server] [--install] [--channel stable|nightly] beeper install desktop [--channel stable|nightly] beeper install server [--channel stable|nightly] [--server-env production|staging] ``` @@ -22,10 +22,36 @@ beeper install server [--channel stable|nightly] [--server-env production|stagi - `setup --oauth` runs browser-based OAuth/PKCE against the resolved target. - `setup --remote URL` configures a remote Beeper Desktop or Server target. - `setup --desktop --install` or `setup --server --install` installs the runtime if missing, then sets up. +- `setup --email` signs in with a verification code sent to an email address — no browser required (see [Headless server setup](#headless-server-setup) below). - `install desktop|server` installs without changing the selected target. - The selected target is persisted in `~/.beeper/config.json` (override with `BEEPER_CLI_CONFIG_DIR`). - For non-interactive use, pass a token in the environment: `BEEPER_ACCESS_TOKEN=… beeper …`. +## Headless server setup + +When running on a machine with no graphical environment (VPS, headless server), +browser-based OAuth is not available. Use the email-based auth flow instead: + +```sh +# 1. Install and start the server +beeper setup --server --install + +# 2. Sign in with email (no browser needed) +beeper auth email start --email you@example.com -t server +# → returns a setupRequestID + +# 3. Enter the verification code received by email +beeper auth email response --code 123456 --setup-request-id -t server --yes + +# 4. Verify the device (approve from another Beeper device, or use your recovery key) +beeper verify recovery-key -t server --key "YOUR_RECOVERY_KEY" + +# 5. Enable auto-start at login +beeper targets enable server +``` + +After step 4 the server reaches `ready` state and bridges begin syncing. + ## Examples ```sh @@ -34,5 +60,6 @@ beeper setup --local beeper setup --oauth beeper setup --remote https://desktop.example.com beeper setup --desktop --install --channel nightly +beeper setup --server --install beeper install server --server-env staging ```