Skip to content

docs: add headless server setup guide #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
juulieen wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add headless server setup guide #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e18df8
docs: add headless server setup guide with email auth flow
juulieen May 27, 2026
be4ec8b
docs: fix command synopsis and recovery-key flag consistency
juulieen May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-…"
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use the same recovery-key command/flag as the auth docs.

This example currently diverges from packages/cli/docs/auth.md (beeper auth verify recovery-key [--code KEY]). Inconsistent command syntax in README can break headless onboarding.

Suggested doc fix 
-$ beeper verify recovery-key -t server --key "XXXX-XXXX-XXXX-…"
+$ beeper auth verify recovery-key -t server --code "XXXX-XXXX-XXXX-…"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
$ beeper verify recovery-key -t server --key "XXXX-XXXX-XXXX-…"
$ beeper auth verify recovery-key -t server --code "XXXX-XXXX-XXXX-…"
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 178, Update the README example to match the auth docs by
replacing the divergent command "beeper verify recovery-key -t server --key
\"XXXX-XXXX-XXXX-…\"" with the canonical "beeper auth verify recovery-key
[--code KEY]" usage; specifically, remove the "-t server" and "--key" form and
use the "beeper auth verify recovery-key" command with the "--code KEY" flag so
README matches packages/cli/docs/auth.md.

Copy link
Copy Markdown
Author

@juulieen juulieen May 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The README example is correct — beeper verify recovery-key -t server --key "..." matches the actual CLI usage. The pre-existing auth.md had the wrong syntax which has been fixed in be4ec8b.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@juulieen, thanks for the clarification! You're right — the README example was correct, and my comment was based on the stale/incorrect syntax in the pre-existing auth.md. Glad that's been fixed in be4ec8b. I'll note the correct command form for future reviews.

✏️ Learnings added 
Learnt from: juulieen
Repo: beeper/cli PR: 13
File: README.md:178-178
Timestamp: 2026-05-27T22:40:16.795Z
Learning: In the beeper CLI, the correct command for recovery-key verification is `beeper verify recovery-key -t <target> --key "<key>"` (top-level `verify` subcommand, `--key` flag). The `auth.md` docs previously had incorrect syntax (`beeper auth verify recovery-key --code KEY`), which was fixed in commit be4ec8b of PR `#13`.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

▎ 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
Expand Down
9 changes: 7 additions & 2 deletions packages/cli/docs/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <addr> # start headless email sign-in
beeper auth email response --code <code> --setup-request-id <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
Expand All @@ -21,7 +23,7 @@ beeper auth verify sas
beeper auth verify sas-confirm
beeper auth verify qr-scan --payload <data>
beeper auth verify qr-confirm
beeper auth verify recovery-key [--code KEY]
beeper verify recovery-key --key <value>
beeper auth verify reset-recovery-key
beeper auth verify cancel
```
Expand All @@ -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`).
Expand All @@ -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 <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
```
29 changes: 28 additions & 1 deletion packages/cli/docs/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
```
Expand All @@ -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 <id-from-step-2> -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"
Copy link
Copy Markdown
Author

@juulieen juulieen May 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified against the actual CLI: beeper verify recovery-key is indeed a top-level command (not under auth), and the flag is --key, not --code.

$ beeper verify recovery-key --help
USAGE
  $ beeper verify recovery-key --key <value> [...]

FLAGS
      --key=<value>       (required) Recovery key string

The pre-existing auth.md had the wrong syntax (beeper auth verify recovery-key [--code KEY]). Fixed in be4ec8b — both auth.md and the new docs now use the correct command.

Comment thread
coderabbitai[bot] marked this conversation as resolved.

# 5. Enable auto-start at login
beeper targets enable server
```

After step 4 the server reaches `ready` state and bridges begin syncing.

## Examples

```sh
Expand All @@ -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
```