feat(cli): add interactive setup wizard (#72)

Adds a -i / --interactive flag that launches a guided terminal wizard
for first-time users. The wizard walks through password, port, access
mode (tunnel type and visibility), and log level, then starts the server
with the chosen config.

Key changes:
- Extract prompt helpers (color, ask, choose, confirm) from service.js
into src/prompts.js so both the service install wizard and the new setup
wizard can share them
- Add src/interactive.js with the wizard flow (runs in an alternate
screen buffer)
- Port validation clamped to 1-65535, passwords masked in summary output
- Alternate screen buffer cleaned up on Ctrl+C
- Docs updated: architecture, configuration, getting-started, README,
landing page, MkDocs index

Closes #71

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

README.md

@@ -46,6 +46,8 @@ termbeam
 
 Scan the QR code printed in your terminal, or open the URL on any device.
 
+> **First time?** Run `termbeam -i` for a guided setup wizard that walks you through password, port, and access mode.
+
 ### Secure by default
 
 TermBeam starts with a tunnel and auto-generated password out of the box — just run `termbeam` and scan the QR code.
@@ -55,6 +57,7 @@ termbeam                        # tunnel + auto-password (default)
 termbeam --password mysecret    # use a specific password
 termbeam --no-tunnel            # LAN-only (no tunnel)
 termbeam --no-password          # disable password protection
+termbeam -i                     # interactive setup wizard
 ```
 
 ## Remote Access
@@ -85,6 +88,7 @@ termbeam [shell] [args...]        # start with a specific shell (default: auto-d
 termbeam --port 8080              # custom port (default: 3456)
 termbeam --host 0.0.0.0           # allow LAN access (default: 127.0.0.1)
 termbeam --lan                    # shortcut for --host 0.0.0.0
+termbeam -i                       # interactive setup wizard
 termbeam service install          # interactive PM2 service setup wizard
 termbeam service uninstall        # stop & remove PM2 service
 termbeam service status           # show PM2 service status
@@ -105,6 +109,7 @@ termbeam service restart          # restart PM2 service
 | `--host <addr>`       | Bind address                                         | `127.0.0.1`    |
 | `--lan`               | Bind to all interfaces (LAN access)                  | Off            |
 | `--log-level <level>` | Log verbosity (error/warn/info/debug)                | `info`         |
+| `-i, --interactive`   | Interactive setup wizard (guided configuration)      | Off            |
 | `-h, --help`          | Show help                                            | —              |
 | `-v, --version`       | Show version                                         | —              |
 

bin/termbeam.js

@@ -10,18 +10,33 @@ if (subcommand === 'service') {
   });
 } else {
   const { createTermBeamServer } = require('../src/server.js');
-  const instance = createTermBeamServer();
+  const { parseArgs } = require('../src/cli');
+  const { runInteractiveSetup } = require('../src/interactive');
 
-  process.on('SIGINT', () => {
-    console.log('\n[termbeam] Shutting down...');
-    instance.shutdown();
-    setTimeout(() => process.exit(0), 500).unref();
-  });
-  process.on('SIGTERM', () => {
-    console.log('\n[termbeam] Shutting down...');
-    instance.shutdown();
-    setTimeout(() => process.exit(0), 500).unref();
-  });
+  async function main() {
+    const baseConfig = parseArgs();
+    let config;
+    if (baseConfig.interactive) {
+      config = await runInteractiveSetup(baseConfig);
+    }
+    const instance = createTermBeamServer(config ? { config } : undefined);
+
+    process.on('SIGINT', () => {
+      console.log('\n[termbeam] Shutting down...');
+      instance.shutdown();
+      setTimeout(() => process.exit(0), 500).unref();
+    });
+    process.on('SIGTERM', () => {
+      console.log('\n[termbeam] Shutting down...');
+      instance.shutdown();
+      setTimeout(() => process.exit(0), 500).unref();
+    });
+
+    instance.start();
+  }
 
-  instance.start();
+  main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
 }

docs/architecture.md

@@ -18,6 +18,8 @@ termbeam/
 │   ├── tunnel.js            # DevTunnel integration
 │   ├── preview.js           # Port preview reverse proxy
 │   ├── service.js           # PM2 service management
+│   ├── interactive.js      # Interactive setup wizard
+│   ├── prompts.js          # Terminal prompt primitives (color, ask, choose, confirm)
 │   ├── shells.js            # Shell detection (cross-platform)
 │   ├── logger.js            # Structured logger with levels
 │   └── version.js           # Smart version detection
@@ -30,6 +32,8 @@ termbeam/
 ├── test/
 │   ├── auth.test.js
 │   ├── cli.test.js
+│   ├── interactive.test.js
+│   ├── prompts.test.js
 │   ├── devtunnel-install.test.js
 │   ├── e2e-keybar.test.js
 │   ├── integration.test.js
@@ -99,6 +103,14 @@ Handles automatic installation of the DevTunnel CLI when it's not found on the s
 
 Manages TermBeam as a background service via PM2. Provides an interactive wizard for `termbeam service install` that walks through configuration (name, password, port, access mode, working directory, log level, boot auto-start). Also handles `service status`, `logs`, `restart`, and `uninstall` subcommands. Generates an ecosystem config file at `~/.termbeam/ecosystem.config.js`.
 
+### `interactive.js` — Setup Wizard
+
+Runs a step-by-step terminal wizard (in an alternate screen buffer) that walks the user through password, port, access mode, and log level configuration. Returns a config object compatible with `createTermBeamServer()`. Invoked by `bin/termbeam.js` when `--interactive` is passed. Uses prompt primitives from `prompts.js`.
+
+### `prompts.js` — Terminal Prompts
+
+Provides ANSI color helpers (`green`, `yellow`, `red`, `cyan`, `bold`, `dim`) and interactive prompt functions (`ask`, `choose`, `confirm`, `createRL`). Extracted from `service.js` so both the service install wizard and the interactive setup wizard can share the same prompt primitives.
+
 ### `version.js` — Version Detection
 
 Smart version that shows `1.0.0` for npm installs and `1.0.0-dev (git-hash)` for local development.

docs/configuration.md

@@ -7,21 +7,22 @@ description: All TermBeam CLI flags and options — ports, passwords, tunnels, s
 
 ## CLI Flags
 
-| Flag                  | Description                                                      | Default        |
-| --------------------- | ---------------------------------------------------------------- | -------------- |
-| `--password <pw>`     | Set access password (also accepts `--password=<pw>`)             | Auto-generated |
-| `--generate-password` | Auto-generate a secure password (default behavior)               | On             |
-| `--no-password`       | Disable password authentication (cannot combine with `--public`) | —              |
-| `--tunnel`            | Create an ephemeral devtunnel URL (private access)               | On             |
-| `--no-tunnel`         | Disable tunnel                                                   | —              |
-| `--persisted-tunnel`  | Create a reusable devtunnel URL (stable across restarts)         | Off            |
-| `--public`            | Allow public tunnel access (no Microsoft login required)         | Off            |
-| `--port <port>`       | Server port                                                      | `3456`         |
-| `--host <addr>`       | Bind address                                                     | `127.0.0.1`    |
-| `--lan`               | Bind to all interfaces (LAN access)                              | Off            |
-| `-h, --help`          | Show help                                                        | —              |
-| `-v, --version`       | Show version                                                     | —              |
-| `--log-level <level>` | Set log verbosity: `error`, `warn`, `info`, `debug`              | `info`         |
+| Flag                  | Description                                                                                                   | Default        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- | -------------- |
+| `--password <pw>`     | Set access password (also accepts `--password=<pw>`)                                                          | Auto-generated |
+| `--generate-password` | Auto-generate a secure password (default behavior)                                                            | On             |
+| `--no-password`       | Disable password authentication (cannot combine with `--public`)                                              | —              |
+| `--tunnel`            | Create an ephemeral devtunnel URL (private access)                                                            | On             |
+| `--no-tunnel`         | Disable tunnel                                                                                                | —              |
+| `--persisted-tunnel`  | Create a reusable devtunnel URL (stable across restarts)                                                      | Off            |
+| `--public`            | Allow public tunnel access (no Microsoft login required)                                                      | Off            |
+| `--port <port>`       | Server port                                                                                                   | `3456`         |
+| `--host <addr>`       | Bind address                                                                                                  | `127.0.0.1`    |
+| `--lan`               | Bind to all interfaces (LAN access)                                                                           | Off            |
+| `-i, --interactive`   | Interactive setup wizard — walks through password, port, access mode (tunnel type, visibility), and log level | Off            |
+| `-h, --help`          | Show help                                                                                                     | —              |
+| `-v, --version`       | Show version                                                                                                  | —              |
+| `--log-level <level>` | Set log verbosity: `error`, `warn`, `info`, `debug`                                                           | `info`         |
 
 ## Environment Variables
 
@@ -99,6 +100,15 @@ termbeam /bin/bash
 termbeam --port 8080 /usr/bin/fish
 ```
 
+### Interactive Setup
+
+```bash
+# Launch the guided setup wizard
+termbeam -i
+```
+
+The wizard walks through password, port, access mode, and log level with an interactive TUI.
+
 ### With Authentication
 
 ```bash

docs/getting-started.md

@@ -27,6 +27,14 @@ termbeam
 
 ## First Run
 
+For a guided setup that walks you through password, port, access mode, and log level:
+
+```bash
+termbeam -i
+```
+
+Or start directly with defaults:
+
 1. Start TermBeam:
 
    ```bash
@@ -43,7 +51,7 @@ termbeam
         ██║   ███████╗██║  ██║██║ ╚═╝ ██║██████╔╝███████╗██║  ██║██║ ╚═╝ ██║
         ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝
 
-     Beam your terminal to any device 📡  v1.5.0
+     Beam your terminal to any device 📡  v1.7.0
 
      Shell:    /bin/zsh
      Session:  a1b2c3d4

docs/index.md

@@ -47,6 +47,7 @@ Built for developers who need quick remote terminal access without the hassle of
 - **Password auth** with auto-generation, rate limiting, and httpOnly cookies
 - **QR code auto-login** with single-use share tokens (5-min expiry)
 - **Shell validation** — only detected shells are allowed
+- **Interactive setup wizard** — run `termbeam -i` for guided configuration
 
 ## Quick Start
 

landing/index.html

@@ -249,7 +249,7 @@ <h3>Instant remote access</h3>
             <h3>Zero config</h3>
             <p>
               No SSH keys, no port forwarding, no config files. Auto-detects your shell on every
-              platform.
+              platform. Run <code>termbeam -i</code> for a guided setup wizard.
             </p>
           </div>
 
@@ -307,7 +307,8 @@ <h2>Three steps. That's it.</h2>
               <h3>Run one command</h3>
               <p>
                 Run <code>npx termbeam</code> in your terminal. TermBeam starts a server, generates
-                a password, and opens a tunnel.
+                a password, and opens a tunnel. First time? Try <code>termbeam -i</code> for a
+                guided setup.
               </p>
             </div>
           </div>

src/cli.js

@@ -31,6 +31,7 @@ Options:
   --host <addr>         Bind address (default: 127.0.0.1)
   --lan                 Bind to 0.0.0.0 (allow LAN access, default: localhost only)
   --log-level <level>   Set log verbosity: error, warn, info, debug (default: info)
+  -i, --interactive     Interactive setup wizard (guided configuration)
   -h, --help            Show this help
   -v, --version         Show version
 
@@ -47,6 +48,7 @@ Examples:
   termbeam --password secret        Start with specific password
   termbeam --persisted-tunnel       Stable tunnel URL across restarts
   termbeam /bin/bash                Use bash instead of default shell
+  termbeam --interactive               Guided setup wizard
   termbeam service install          Set up as background service (PM2)
 
 Environment:
@@ -241,6 +243,7 @@ function parseArgs() {
   let noTunnel = false;
   let persistedTunnel = false;
   let publicTunnel = false;
+  let interactive = false;
   let explicitPassword = !!password;
 
   const args = process.argv.slice(2);
@@ -281,6 +284,8 @@ function parseArgs() {
       host = '0.0.0.0';
     } else if (args[i] === '--host' && args[i + 1]) {
       host = args[++i];
+    } else if (args[i] === '--interactive' || (args[i] === '-i' && filteredArgs.length === 0)) {
+      interactive = true;
     } else if (args[i] === '--log-level' && args[i + 1]) {
       logLevel = args[++i];
     } else {
@@ -335,6 +340,7 @@ function parseArgs() {
     defaultShell,
     version,
     logLevel,
+    interactive,
   };
 }