beeper · batuhan · Sep 25, 2026 · May 27, 2026 · May 27, 2026 · Sep 25, 2026
diff --git a/README.md b/README.md
@@ -159,6 +159,19 @@ $ beeper accounts add
 
 Variants: `beeper install server`, `beeper install server --server-env staging`.
 
+#### Headless server (no browser)
+
+On a VPS or any machine without a browser, sign in with an emailed code.
+`setup` prompts for the code, then starts device verification:
+
+```sh
+beeper setup --server --install --email you@example.com
+beeper verify recovery-key -t server --key "ABCD-EFGH-IJKL-MNOP"  # if no other device can approve
+beeper targets enable server                                      # start at login
+```
+
+Scripts, agents, and start-at-boot: [Headless server setup](https://github.com/beeper/cli/blob/main/packages/cli/docs/setup.md#headless-server-setup).
+
 ### 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/README.md b/packages/cli/README.md
@@ -159,6 +159,19 @@ $ beeper accounts add
 
 Variants: `beeper install server`, `beeper install server --server-env staging`.
 
+#### Headless server (no browser)
+
+On a VPS or any machine without a browser, sign in with an emailed code.
+`setup` prompts for the code, then starts device verification:
+
+```sh
+beeper setup --server --install --email you@example.com
+beeper verify recovery-key -t server --key "ABCD-EFGH-IJKL-MNOP"  # if no other device can approve
+beeper targets enable server                                      # start at login
+```
+
+Scripts, agents, and start-at-boot: [Headless server setup](https://github.com/beeper/cli/blob/main/packages/cli/docs/setup.md#headless-server-setup).
+
 ### 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
@@ -12,25 +12,28 @@ target file under `~/.beeper/targets/`; `BEEPER_ACCESS_TOKEN` overrides it.
 ```sh
 beeper auth status
 beeper auth logout
-beeper auth verify [--user @id]                         # interactive happy-path
-beeper auth verify start    [--user @id]                # individual steps
-beeper auth verify status
-beeper auth verify list | show
-beeper auth verify approve  [--id active] [--code …]
-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 auth verify reset-recovery-key
-beeper auth verify cancel
+beeper auth email start     --email <addr>                          # headless sign-in, step 1
+beeper auth email response  --setup-request-id <id> --code <code>   # step 2
+beeper verify [--user @id]                                          # interactive happy-path
+beeper verify start         [--user @id]                            # individual steps
+beeper verify status
+beeper verify list | show
+beeper verify approve       [--id active]
+beeper verify sas
+beeper verify sas-confirm
+beeper verify qr-scan       --payload <data>
+beeper verify qr-confirm
+beeper verify recovery-key  --key <value>
+beeper verify reset-recovery-key
+beeper verify cancel
 ```
 
 ## Notes
 
 - `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 verify` (no subcommand) walks the most common SAS/emoji verification flow interactively.
+- `auth email start` + `auth email response` sign in with an emailed code, no browser and no prompts. `response` also takes `--username <name> --yes` when the email has no Beeper account yet. Walkthrough: [Headless server setup](setup.md#headless-server-setup).
+- `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`).
 - `recovery-key` and `reset-recovery-key` apply to the encrypted-messages key, not to Beeper account login.
@@ -39,8 +42,10 @@ beeper auth verify cancel
 
 ```sh
 beeper auth status --json
-beeper auth verify
-beeper auth verify recovery-key --code ABCD-EFGH-IJKL-MNOP
-beeper auth verify reset-recovery-key
+beeper auth email start --email you@example.com -t server --json
+beeper auth email response --setup-request-id <id> --code 123456 -t server --json
+beeper verify
+beeper verify recovery-key -t server --key "ABCD-EFGH-IJKL-MNOP"
+beeper verify reset-recovery-key
 beeper auth logout
 ```
diff --git a/packages/cli/docs/setup.md b/packages/cli/docs/setup.md
@@ -11,7 +11,8 @@ Server / remote targets.
 ## Commands
 
 ```sh
-beeper setup [--local | --oauth | --remote URL | --desktop | --server] [--install] [--channel stable|nightly]
+beeper setup [--local | --oauth | --email ADDR]
+beeper setup [--remote URL | --desktop | --server] [--email ADDR] [--install] [--channel stable|nightly]
 beeper install desktop [--channel stable|nightly]
 beeper install server  [--channel stable|nightly] [--server-env production|staging]
 ```
@@ -22,10 +23,49 @@ 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 ADDR` signs in with an emailed code instead of a browser. Combine it with `--server`, `--desktop`, or `--remote URL`; see [Headless server setup](#headless-server-setup).
 - `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
+
+No browser on the machine (VPS, SSH-only box)? Sign in with an emailed code:
+
+```sh
+beeper setup --server --install --email you@example.com
+```
+
+`setup` installs and starts Beeper Server, emails you a code, prompts for it,
+then starts device verification: approve it from another signed-in Beeper
+device. Server already installed? Drop `--install`. No other device? Use your
+recovery key:
+
+```sh
+beeper verify recovery-key -t server --key "ABCD-EFGH-IJKL-MNOP"
+```
+
+Keep the server running across reboots:
+
+```sh
+beeper targets enable server          # systemd user unit on Linux, launchd agent on macOS
+sudo loginctl enable-linger "$USER"   # Linux: start user units at boot, not at first login
+```
+
+### Scripts and agents
+
+`setup --email` prompts for the code. Without a TTY, sign in with two calls:
+
+```sh
+beeper setup --server --install --yes
+beeper auth email start --email you@example.com -t server --json     # returns setupRequestID
+beeper auth email response --setup-request-id <id> --code <code> -t server --json
+beeper verify recovery-key -t server --key "$BEEPER_RECOVERY_KEY" --json
+```
+
+If the email has no Beeper account yet, add `--username <name> --yes` to
+`auth email response` to create one and accept the terms.
+
 ## Examples
 
 ```sh
@@ -34,5 +74,6 @@ beeper setup --local
 beeper setup --oauth
 beeper setup --remote https://desktop.example.com
 beeper setup --desktop --install --channel nightly
+beeper setup --server --install --email you@example.com
 beeper install server --server-env staging
 ```
diff --git a/packages/cli/scripts/generate-readme.ts b/packages/cli/scripts/generate-readme.ts
@@ -194,6 +194,19 @@ $ beeper accounts add
 
 Variants: \`beeper install server\`, \`beeper install server --server-env staging\`.
 
+#### Headless server (no browser)
+
+On a VPS or any machine without a browser, sign in with an emailed code.
+\`setup\` prompts for the code, then starts device verification:
+
+\`\`\`sh
+beeper setup --server --install --email you@example.com
+beeper verify recovery-key -t server --key "ABCD-EFGH-IJKL-MNOP"  # if no other device can approve
+beeper targets enable server                                      # start at login
+\`\`\`
+
+Scripts, agents, and start-at-boot: [Headless server setup](https://github.com/beeper/cli/blob/main/packages/cli/docs/setup.md#headless-server-setup).
+
 ### 3. Remote Desktop or Server via OAuth (PKCE)
 
 For a Beeper Desktop or Server running on another machine, authorize the CLI