docs: add headless server setup guide#13
Conversation
Document the email-based authentication flow for setting up Beeper Server on machines without a graphical environment (VPS, headless servers). Closes beeper#12 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
📜 Recent review details🧰 Additional context used🧠 Learnings (2)📚 Learning: 2026-05-27T22:40:16.795ZApplied to files:
📚 Learning: 2026-05-27T22:40:20.614ZApplied to files:
🔇 Additional comments (2)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis PR adds documentation for a complete headless server setup flow and a two-step browserless email sign-in ( ChangesHeadless Email Auth Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds documentation for the new email-based (headless) authentication flow, intended for environments without a browser such as VPS/headless servers.
Changes:
- Documents
beeper auth email start/auth email responsecommands inauth.md. - Adds a "Headless server setup" walkthrough section to
setup.md. - Adds a headless server example block to the top-level
README.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| packages/cli/docs/setup.md | Adds --email bullet and a step-by-step headless setup walkthrough. |
| packages/cli/docs/auth.md | Documents the new email sign-in subcommands and adds usage examples. |
| README.md | Adds a "Headless server" section with a sample end-to-end session. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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" |
There was a problem hiding this comment.
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.
![coderabbitai[bot]](https://ghub.bbstale.com/avatars/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/cli/docs/setup.md (1)
14-14:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd
setup --emailis documented in Notes, but not listed in thebeeper setup [...]command line. This can mislead users scanning the command header first.Suggested doc fix
-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]Also applies to: 25-25
🤖 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 `@packages/cli/docs/setup.md` at line 14, Update the command synopsis string "beeper setup [--local | --oauth | --remote URL | --desktop | --server] [--install] [--channel stable|nightly]" to include the --email option (e.g. add " --email" in the bracketed options) so it matches the Notes section; make the same change for the other identical occurrence mentioned (the second synopsis at the other location). Ensure the displayed usage explicitly lists --email alongside the other flags so the header and Notes remain consistent.
🤖 Prompt for all review comments with 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.
Inline comments:
In `@packages/cli/docs/setup.md`:
- Line 47: The README line uses the wrong CLI syntax; replace the incorrect
command "beeper verify recovery-key -t server --key \"YOUR_RECOVERY_KEY\"" with
the documented auth subcommand and correct flag, e.g. "beeper auth verify
recovery-key --code YOUR_RECOVERY_KEY" so it matches the usage in auth.md
(update references to the recovery-key, verify, auth verify, --key -> --code
accordingly).
In `@README.md`:
- 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.
---
Outside diff comments:
In `@packages/cli/docs/setup.md`:
- Line 14: Update the command synopsis string "beeper setup [--local | --oauth |
--remote URL | --desktop | --server] [--install] [--channel stable|nightly]" to
include the --email option (e.g. add " --email" in the bracketed options) so it
matches the Notes section; make the same change for the other identical
occurrence mentioned (the second synopsis at the other location). Ensure the
displayed usage explicitly lists --email alongside the other flags so the header
and Notes remain consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4f6c67c1-4f27-4ea1-a704-d085419ed1ad
📒 Files selected for processing (3)
README.mdpackages/cli/docs/auth.mdpackages/cli/docs/setup.md
📜 Review details
🔇 Additional comments (1)
packages/cli/docs/auth.md (1)
15-16: LGTM!Also applies to: 35-35, 45-46
| $ 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-…" |
There was a problem hiding this comment.
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.
| $ 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
- Add --email to setup command synopsis - Fix recovery-key command: it's `beeper verify recovery-key --key` (top-level), not `beeper auth verify recovery-key --code` - Verified against actual CLI --help output Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
All review comments addressed in be4ec8b:
|
Summary
setup.mdwith a step-by-step guide for email-based authentication (no browser required)auth email startandauth email responsecommands inauth.mdREADME.mdunder the "Local Beeper Server" sectionCloses #12
Context
Setting up Beeper Server on a headless machine (VPS, remote server) currently defaults to browser-based OAuth which fails without a graphical environment. The CLI already supports an email-based auth flow (
auth email start→auth email response) that works perfectly for this use case, but it was not documented.Test plan
🤖 Generated with Claude Code