codebase-onboarder 0.3.1 → 0.4.1

package/README.md

@@ -212,7 +212,13 @@ onboarder config show                    # current settings (key masked)
 onboarder config set host 0.0.0.0        # direct VPS/LAN access (domain optional)
 onboarder config set port 4311           # move away from a busy port
 onboarder config key rotate              # mint a new access key
-onboarder status                         # running PID, stopped, or unmanaged port owner
+onboarder start                          # foreground; Ctrl-C stops it
+onboarder start background               # detached; keeps running after you close the terminal
+onboarder logs                           # last 40 log lines  (-n <count>, -f to follow)
+onboarder start startup install          # also start automatically at every login
+onboarder start startup status           # is a login item installed, and is it live?
+onboarder start startup remove           # take the login item back out
+onboarder status                         # running PID, mode, uptime, stopped, or unmanaged port owner
 onboarder stop                           # stop a PID-file-managed instance
 onboarder restart                        # graceful stop, then start
 onboarder tunnel cloudflare              # expose via a Cloudflare quick tunnel
@@ -223,6 +229,60 @@ onboarder https status                   # domain, URL, Caddyfile, and Caddy sta
 onboarder doctor                         # config, access key, ports, DNS, TLS, and tunnels
 ```
 
+### Running it in the background
+
+`onboarder start` runs in the foreground on purpose: it is a normal command, and Ctrl-C stops it. When you want the server to outlive the terminal, use `start background`. It re-launches the same CLI as a detached process with its output going to `onboarder.log` beside your config, then **waits for the server to actually answer** `/api/health` before reporting success. A port conflict comes back as a failure with the log tail attached, not as a cheerful green light that dies a second later.
+
+```bash
+onboarder start background   # returns once it is serving
+onboarder logs -f            # watch it, Ctrl-C to stop watching (not the server)
+onboarder stop               # stop it
+```
+
+Log lines are column-aligned — a fixed-width local timestamp, a fixed-width level, then the message — so a wall of requests stays scannable:
+
+```
+16:09:38  INFO   GET /api/scan 200 (1.2s)
+16:09:46  INFO   POST /api/auth/login 200 (2ms)
+16:10:03  WARN   could not write the run record error=EACCES
+```
+
+### What gets logged (and what does not)
+
+A single page load pulls ~90 ES modules, a stylesheet, and two vendored libraries. Logging each one buries every real event — a scan, a login, a 500 — under a hundred lines that describe nobody doing anything, repeated on every reload. So requests are classified:
+
+| Request | Logged? |
+|---|---|
+| `GET /api/…` (a scan, a login, a settings save) | **yes** — this is a person doing something |
+| Any `POST`/`PUT`/`DELETE` | **yes**, whatever the path |
+| Any `4xx` or `5xx` | **yes** — a missing asset is a broken build, a 500 is a bug |
+| `GET /api/health` (uptime poll) | no — it is not an event |
+| `GET /app.js`, `/js/tree.js`, `/styles.css`, `/vendor/…` | **counted, not printed** |
+
+Suppressed assets are not thrown away. Every 40 of them, one dim footnote is printed, so an idle terminal still says what it served rather than looking dead:
+
+```
+16:09:38           served 40 static files in 1.9s
+```
+
+`LOG_LEVEL=debug` (or `ONBOARDER_LOG_VERBOSE=1`) turns every request back on for when you are debugging the server rather than watching it. `ONBOARDER_LOG=json` switches the format to one JSON object per line for anything parsing the log.
+
+### Terminal width
+
+Every panel and log line is fitted to the terminal it is printed into, and a foreground `onboarder start` redraws its panel on `SIGWINCH` — resize the window and the border stays on screen instead of hanging off the edge. Long values are elided in the middle (the tail of a path is the part that identifies it), and below 52 columns the level column is dropped to make room for the message.
+
+### Starting at login
+
+`onboarder start startup install` registers Onboarder with whatever your OS uses for login items, and never asks for `sudo`:
+
+| Platform | What it writes | How it loads |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.onboarder.server.plist` | `launchctl bootstrap gui/$UID` |
+| Linux | `~/.config/systemd/user/onboarder.service` | `systemctl --user enable --now` |
+| Windows | `%APPDATA%\...\Startup\Onboarder.cmd` | the file *is* the registration |
+
+All three run the same `onboarder start --config <your config>`, so a login-started server is indistinguishable from a hand-started one — same config, same pid file, same `onboarder stop`. The generated unit uses `Restart=on-failure` (and launchd's `KeepAlive`/`SuccessfulExit=false`), so a crash is restarted but a deliberate `onboarder stop` stays stopped. `onboarder start startup remove` unloads and deletes it; a running server is left alone. On a platform with no known mechanism, the command says so instead of pretending.
+
 A fresh self-hosted setup uses `0.0.0.0`, so a VPS is reachable at `http://<server-ip>:<port>` without a reverse proxy. The server accepts IPv4 and IPv6 IP literals, including a public address that reaches the host through provider NAT, but still rejects arbitrary DNS Host headers. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
 
 When a remote browser opens the URL, Onboarder shows its themed sign-in page. The access key is sent in a POST body—not in the URL—and the browser stores only the signed session cookie. Opening the same server through `http://localhost:<port>` on that machine skips the page. Caddy and tunnel connections remain authenticated because their public Host is not loopback.
@@ -255,7 +315,11 @@ codebase-onboarder/
 ├── server/          # Zero-dependency Node.js HTTP server
 │   ├── index.js     # createServer / startServer / startup banner
 │   ├── config.js    # Settings schema, normalization, atomic 0600 writes
-│   ├── pidfile.js   # PID ownership for status / stop / restart
+│   ├── pidfile.js   # PID + run record (mode, url, log) for status / stop / restart
+│   ├── daemon.js    # Detached background start, log file, readiness probe
+│   ├── startup.js   # Login items: launchd plist / systemd --user unit / Startup folder
+│   ├── logger.js    # Aligned-text or JSON log lines from one entry shape
+│   ├── layout.js    # Shared terminal geometry: width, fit, panel, resize
 │   ├── router.js    # Route table, live per-request settings, auth & CSRF gates
 │   ├── auth.js      # Signed HttpOnly browser sessions
 │   ├── apiAuth.js   # Login/status/logout endpoints

package/cli/commands.js

@@ -12,13 +12,15 @@ import { spawn } from 'node:child_process';
 
 import {
   DEFAULT_SETTINGS, configPath, configExists, readSettings, writeSettings,
-  publicSettings, serverUrls, maskAccessKey,
+  publicSettings, serverUrls, maskAccessKey, isLoopbackHost,
 } from '../server/config.js';
 import { startServer } from '../server/index.js';
-import { pidIsAlive, readPidFile, removePidFile } from '../server/pidfile.js';
+import { pidIsAlive, readPidFile, removePidFile, readRunInfo, runInfoPath } from '../server/pidfile.js';
+import { logPath, rotateLogIfNeeded, tailLog, followLog, logExists, spawnDetached, waitForPidFile, waitForReady } from '../server/daemon.js';
+import { installStartup, removeStartup, startupStatus, startupTarget } from '../server/startup.js';
 import { tunnelStatus, cloudflareCommand, tailscaleCommand, installHint, findOnPath } from '../server/tunnel.js';
 import { caddyRun, caddyValidate, httpsReadiness, httpsStatus, writeCaddyfile } from '../server/https.js';
-import { bold, cyan, dim, ok, warn, bad, kv, tick, cross, dash, welcomeBanner } from './ui.js';
+import { bold, cyan, dim, ok, warn, bad, paint, kv, tick, cross, dash, welcomeBanner, panel, row, hint } from './ui.js';
 import { buildSteps, unansweredSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
 import { runSteps, WizardCancelled } from './prompt.js';
 
@@ -41,6 +43,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
       printSummary(out, settings, { revealKey: Boolean(patchHasNewKey(flags)) });
     }
     await printTunnelFollowup(out, settings);
+    // `start` may be the flag `--start` (true) or the mode a subcommand asked
+    // for ('background') — both mean "boot it now", differently.
+    if (flags.start === 'background') return runStartBackground({ flags, out, err });
     if (flags.start) return runStart({ flags, out, err });
     return 0;
   }
@@ -95,9 +100,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
   }
   await printTunnelFollowup(out, settings);
 
-  if (flags.start || await confirm(out, 'Start Onboarder now?', true)) {
+  if (flags.start === 'background' || (!flags.start && await confirm(out, 'Start Onboarder now?', true))) {
     out('');
-    return runStart({ flags, out, err });
+    return flags.start === 'background' ? runStartBackground({ flags, out, err }) : runStart({ flags, out, err });
   }
   out(dim(settings.https
     ? '  Later: `onboarder start` (starts Caddy automatically), or `onboarder https status`'
@@ -145,6 +150,66 @@ async function printTunnelFollowup(out, settings) {
 
 // ---------------------------------------------------------------- start ---
 
+// What the person is about to be looking at, as a titled panel instead of a
+// loose run of lines. One function serves the foreground banner and the
+// background confirmation, so "what does `onboarder start` tell me" has exactly
+// one answer no matter which mode you used.
+export function serverDetails(started, { configFile, pid = null, mode = 'foreground', logFile = '' } = {}) {
+  const { settings, host, port } = started;
+  const urls = serverUrls(settings);
+  const rows = [
+    row('URL', bold(cyan(urls.local))),
+    row('Bind', `${host}:${port}`),
+    row('Mode', settings.mode === 'self-hosted'
+      ? (isLoopbackHost(host) ? 'self-hosted (loopback — use a tunnel for remote access)' : 'self-hosted (network reachable, access key required)')
+      : 'local (this machine only)'),
+  ];
+  if (urls.network) rows.push(row('Network', urls.network));
+  if (urls.domain) rows.push(row('Public', urls.domain));
+  if (settings.mode === 'self-hosted') {
+    rows.push(row('Access key', settings.accessKey ? maskAccessKey(settings.accessKey) : bad('NOT SET — every API call is refused')));
+  }
+  rows.push(row('PID', String(pid ?? process.pid)));
+  rows.push(row('Config', dim(configFile || '')));
+  if (logFile) rows.push(row('Logs', dim(logFile)));
+  return { rows, urls, mode };
+}
+
+function printServerDetails(out, started, options) {
+  const { rows } = serverDetails(started, options);
+  out('');
+  out(panel('Onboarder is running', rows));
+  out('');
+}
+
+// Keep a foreground panel at the terminal's current width.
+//
+// Resizing a window after the server started used to leave a panel whose right
+// border was off-screen — the information was correct but unreadable, which is
+// the same complaint as "it messes up the terminal". On SIGWINCH we redraw the
+// block in place: move the cursor up over the lines we own, clear them, and
+// reprint at the new width. Only the panel is redrawn, not the log scrollback
+// above it, so nothing the user has already read is disturbed.
+//
+// A non-TTY (a pipe, a log file) never redraws: there is no cursor to move and
+// re-printing would just duplicate the block.
+export function watchResize(render, stream = process.stdout) {
+  if (!stream.isTTY || typeof process.stdout.on !== 'function') return () => {};
+  let previous = '';
+  const onResize = () => {
+    const next = render();
+    if (next === previous) return;
+    const lines = previous ? previous.split('\n').length : 0;
+    // Up over the old block, clear it, print the new one. `\x1b[J` clears from
+    // the cursor to the end of the screen, which is exactly the old block.
+    stream.write(lines ? `\x1b[${lines}A\x1b[J` : '');
+    stream.write(next);
+    previous = next;
+  };
+  process.stdout.on('SIGWINCH', onResize);
+  return () => process.stdout.removeListener('SIGWINCH', onResize);
+}
+
 export async function runStart({ flags = {}, out = console.log, err = console.error } = {}) {
   const file = flags.config || configPath();
   if (!await configExists(file)) {
@@ -165,7 +230,9 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
   }
   if (recorded) removePidFile(file, recorded);
 
-  const started = await startServer({ configFile: file, log: out });
+  // `quiet`: the CLI prints its own details panel below, so the loose banner
+  // would be the same facts twice. `node server/index.js` still gets the banner.
+  const started = await startServer({ configFile: file, log: () => {}, openBrowser: false });
   if (started.settings.https) {
     out('');
     const httpsCode = await runHttps('setup', { flags, out: flags.json ? () => {} : out, err });
@@ -175,13 +242,119 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
     }
   }
   if (flags.json) out(JSON.stringify({ host: started.host, port: started.port, url: serverUrls(started.settings).local }));
+  // `start` foreground prints the details itself rather than letting
+  // `startServer` print the old loose banner — the panel replaces it. The
+  // background child lands here too (that is the point of reusing this path),
+  // and ONBOARDER_BACKGROUND is what tells the two apart: one is attached to a
+  // terminal you are about to close, the other is already detached from it.
+  printServerDetails(out, started, { configFile: file, mode: 'foreground' });
+  // Redraw the panel when the terminal is resized, so the border stays on screen
+  // and long paths re-elide to the new width instead of hanging off the edge.
+  watchResize(() => '\n' + panel('Onboarder is running', serverDetails(started, { configFile: file }).rows) + '\n');
+  if (process.env.ONBOARDER_LAUNCH) {
+    // Started by launchd/systemd/the Startup folder: these lines are going into
+    // a log file nobody is watching, so they say what the supervisor is doing
+    // rather than telling a person to press Ctrl-C.
+    out(dim(`  Launched at login by ${process.env.ONBOARDER_LAUNCH}. This process is supervised — stop it with \`onboarder stop\`.`));
+  } else if (process.env.ONBOARDER_BACKGROUND) {
+    out(dim('  Started in the background — this process is now independent of any terminal.'));
+  } else {
+    out(dim('  Running in the foreground. Ctrl-C stops it; closing this terminal stops it too.'));
+    out(dim('  To keep it alive after you close the terminal: ') + cyan('onboarder start background'));
+  }
+  out('');
   // The listening server holds the event loop; resolve so callers/tests know
   // we are up, but leave the process running.
   return { ...started, code: 0 };
 }
 
+// `onboarder start background` — same server, no terminal attached. The child is
+// an ordinary foreground `start`; all this does is detach it and then *wait for
+// it to answer* before reporting success, so a bind failure surfaces here as a
+// failure with the log tail attached rather than a cheerful lie.
+export async function runStartBackground({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  if (!await configExists(file) && process.stdout.isTTY && !flags.nonInteractive) {
+    out(dim('  No settings yet — running setup first.'));
+    return runSetup({ flags: { ...flags, start: 'background' }, out, err });
+  }
+  const recorded = readPidFile(file);
+  if (recorded && pidIsAlive(recorded)) {
+    err(`  Onboarder is already running (PID ${recorded}).`);
+    err(dim('    Use `onboarder status`, `onboarder stop`, or `onboarder restart`.'));
+    return 1;
+  }
+  if (recorded) removePidFile(file, recorded);
+
+  const settings = await readSettings(file);
+  const log = logPath(file);
+  await rotateLogIfNeeded(log);
+
+  spawnDetached({ configFile: file, log });
+  const pid = await waitForPidFile(file, { timeoutMs: flags.timeout ? Number(flags.timeout) * 1000 : 20000 });
+  const urls = serverUrls(settings);
+  const ready = pid ? await waitForReady(new URL('/api/health', urls.local).toString(), { timeoutMs: 8000 }) : false;
+
+  if (!ready) {
+    // Two different failures with two different fixes, so they are reported
+    // differently. No pid record means the child never finished binding — the
+    // log holds the reason (a busy port, an invalid config). A live pid that will
+    // not answer means it bound and then something in front of it is in the way
+    // (a proxy, a firewall), and no amount of log-reading will show that.
+    if (!pid) {
+      err(bad('  Onboarder did not start in the background.'));
+      const tail = await tailLog(log, 15);
+      if (tail.length) {
+        err(dim(`  Last lines of ${log}:`));
+        for (const line of tail) err('    ' + line);
+      }
+      err(dim('    Fix the cause above, then run `onboarder start background` again.'));
+    } else {
+      err(bad(`  Onboarder is running (PID ${pid}) but ${urls.local} is not answering.`));
+      err(dim(`    Its log is ${log}. If a proxy or firewall fronts this port, check that first.`));
+      err(dim('    Otherwise: `onboarder stop`, then `onboarder start background` again.'));
+    }
+    return 1;
+  }
+
+  if (flags.json) {
+    out(JSON.stringify({ background: true, pid, url: urls.local, log, configFile: file }, null, 2));
+    return 0;
+  }
+
+  out('');
+  out(panel('Onboarder is running in the background', [
+    row('URL', bold(cyan(urls.local))),
+    row('PID', String(pid)),
+    row('Mode', 'background — survives closing this terminal'),
+    row('Logs', dim(log)),
+    row('Config', dim(file)),
+  ]));
+  out('');
+  out(dim('  Follow the log: ') + cyan('onboarder logs -f'));
+  out(dim('  Stop it:         ') + cyan('onboarder stop'));
+  out(dim('  Check on it:     ') + cyan('onboarder status'));
+  out('');
+  return 0;
+}
+
+
 // ------------------------------------------------------------- lifecycle ---
 
+// Panel rows carry their own inline marker rather than the `tick`/`cross`/`dash`
+// constants: those bake in a two-column indent for standalone lines, which would
+// push the first row out of the panel's label column.
+const MARK = { yes: (s) => paint('✓ ', 'green') + s, no: (s) => paint('– ', 'gray') + s, warn: (s) => paint('! ', 'yellow') + s };
+
+// How a live instance presents itself, in one sentence per mode. The point of
+// the sentence is the thing someone actually needs to know: can I close my
+// terminal, or will that kill it?
+const MODE_NOTES = {
+  background: 'background — survives closing the terminal',
+  startup: 'started at login — the OS restarts it if it stops',
+  foreground: 'foreground — stops when you press Ctrl-C or close the terminal',
+};
+
 export async function runStatus({ flags = {}, out = console.log } = {}) {
   const file = flags.config || configPath();
   const pid = readPidFile(file);
@@ -190,6 +363,9 @@ export async function runStatus({ flags = {}, out = console.log } = {}) {
   try { settings = await readSettings(file); } catch { /* defaults are still meaningful */ }
   const portBusy = settings ? !(await portIsFree(settings.host, settings.port)) : false;
   if (pid && !running) removePidFile(file, pid);
+  // The pid says whether it is up; the run record says *how* it came up, which
+  // is what tells someone whether closing their terminal will kill it.
+  const info = running ? readRunInfo(file) : null;
   const result = {
     running: Boolean(running || portBusy),
     pid: running ? pid : null,
@@ -197,21 +373,53 @@ export async function runStatus({ flags = {}, out = console.log } = {}) {
     portBusy,
     managed: Boolean(running),
     configFile: file,
+    mode: running ? (info?.mode || 'foreground') : null,
+    url: running ? (info?.url || (settings ? serverUrls(settings).local : null)) : null,
+    uptimeMs: running && info?.startedAt ? Date.now() - Date.parse(info.startedAt) : null,
+    log: running && info?.log ? info.log : null,
+    startup: (await startupStatus()).installed,
   };
   if (flags.json) {
     out(JSON.stringify(result, null, 2));
   } else {
     out('');
-    out(bold('  Onboarder status'));
-    if (running) out(`${tick}Running    PID ${pid}`);
-    else if (portBusy) out(`${warn('!')}Port busy  ${result.port} (no Onboarder PID record)`);
-    else out(`${dash}Stopped`);
-    out(kv('Config', file));
-    if (result.portBusy && !running) out(dim('    Inspect it with `ss -ltnp` or `lsof -i :' + settings.port + '` before stopping another process.'));
+    out(panel('Onboarder status', [
+      row('State', running
+        ? MARK.yes(`Running (PID ${pid})`)
+        : portBusy
+          ? MARK.warn(`Port busy — ${result.port}, but no Onboarder process record`)
+          : MARK.no('Stopped')),
+      ...(running ? [
+        row('URL', cyan(result.url || '')),
+        row('Mode', MODE_NOTES[result.mode] || MODE_NOTES.foreground),
+        ...(result.uptimeMs ? [row('Uptime', humanDuration(result.uptimeMs))] : []),
+        ...(result.log ? [row('Logs', dim(result.log))] : []),
+      ] : []),
+      row('Config', dim(file)),
+      row('At login', result.startup ? MARK.yes('Enabled') : MARK.no('Not enabled — `onboarder start startup install`')),
+      ...(result.portBusy && !running
+        ? [hint('Inspect the listener with `ss -ltnp` or `lsof -i :' + settings.port + '` before stopping another process.')]
+        : []),
+    ]));
+    out('');
   }
   return 0;
 }
 
+// "3d 4h", "12m 5s" — coarse on purpose. Precision past the second is noise on
+// something a person glances at.
+export function humanDuration(ms) {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const days = Math.floor(total / 86400);
+  const hours = Math.floor((total % 86400) / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  if (days) return `${days}d ${hours}h`;
+  if (hours) return `${hours}h ${minutes}m`;
+  if (minutes) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
 function waitForExit(pid, timeoutMs = 5000) {
   return new Promise((resolve) => {
     const started = Date.now();
@@ -274,6 +482,109 @@ export async function runRestart(options = {}) {
   return runStart(options);
 }
 
+// ----------------------------------------------------------------- logs ---
+
+// `onboarder logs` — the answer to "it is running in the background, what is it
+// doing?". Prints the tail of the same file the background child writes, and
+// `-f` follows it. Line-oriented and level-colored, so a wall of request logs
+// stays scannable instead of being one undifferentiated block.
+export async function runLogs({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const log = logPath(file);
+  const lines = flags.lines === undefined ? 40 : Math.max(1, Number(flags.lines) || 40);
+  if (!await logExists(log)) {
+    if (flags.json) out(JSON.stringify({ log, exists: false, lines: [] }, null, 2));
+    else {
+      err(`  No log file yet at ${log}.`);
+      err(dim('    A foreground `onboarder start` prints to the terminal; only `onboarder start background` writes this file.'));
+    }
+    return flags.json ? 0 : 1;
+  }
+  if (!flags.follow) {
+    const tail = await tailLog(log, lines);
+    if (flags.json) { out(JSON.stringify({ log, exists: true, lines: tail }, null, 2)); return 0; }
+    out('');
+    out(bold(`  ${log}`) + dim(`  (last ${tail.length} of ${lines})`));
+    out('');
+    for (const line of tail) out('  ' + line);
+    out('');
+    return 0;
+  }
+  if (flags.json) { err('  --follow and --json do not combine; pick one.'); return 2; }
+  out('');
+  out(bold(`  Following ${log}`) + dim('  (Ctrl-C to stop)'));
+  out('');
+  const stop = followLog(log, (line) => out('  ' + line), { from: 'start' });
+  const finish = () => { stop(); process.exit(0); };
+  process.once('SIGINT', finish);
+  await new Promise((resolve) => process.once('exit', resolve));
+  return 0;
+}
+
+// -------------------------------------------------------------- startup ---
+
+// `onboarder start startup` — run at login, not just right now. Three verbs
+// because the three actions are genuinely different: `install` writes the
+// artifact and hands it to the OS, `remove` takes it back out, `status` only
+// looks. `install` also starts it once so the person is not left waiting for the
+// next reboot to find out whether it worked.
+export async function runStartup(action = 'status', { flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const target = startupTarget();
+  const log = logPath(file);
+
+  if (action === 'install' || action === 'enable' || action === 'on') {
+    const result = await installStartup({ configFile: file, log, target });
+    if (!result.ok) {
+      err(bad('  Could not install the startup entry.'));
+      err('    ' + (result.reason || result.output || result.error || 'unknown error'));
+      return 1;
+    }
+    out(tick + `Onboarder will start at login (${target.hint}).`);
+    out(kv('Startup file', result.path));
+    if (result.output) out(dim('    ' + result.output.split('\n').slice(-2).join('\n    ')));
+    out('');
+    out(dim('  Start it right now too: ') + cyan('onboarder start background'));
+    out(dim('  Turn it off again:      ') + cyan('onboarder start startup remove'));
+    out('');
+    return 0;
+  }
+
+  if (action === 'remove' || action === 'disable' || action === 'off' || action === 'uninstall') {
+    const status = await startupStatus(target);
+    if (!status.installed) {
+      out(dash + 'No startup entry is installed — nothing to remove.');
+      return 0;
+    }
+    const result = await removeStartup({ target });
+    if (!result.ok) { err(bad('  Could not remove the startup entry: ' + (result.reason || 'unknown error'))); return 1; }
+    out(tick + 'Startup entry removed. A running server is untouched — use `onboarder stop` for that.');
+    out(kv('Removed', result.path));
+    out('');
+    return 0;
+  }
+
+  if (action === 'status' || action === undefined) {
+    const status = await startupStatus(target);
+    if (flags.json) { out(JSON.stringify(status, null, 2)); return status.installed ? 0 : 1; }
+    out('');
+    out(panel('Onboarder at login', [
+      row('State', status.installed
+        ? (status.active ? MARK.yes('Enabled and running') : MARK.warn('Enabled, not running'))
+        : MARK.no('Not enabled')),
+      row('How', status.detail),
+      ...(status.path ? [row('File', dim(status.path))] : []),
+      ...(status.supported ? [hint(status.installed
+        ? 'Remove it with `onboarder start startup remove`.'
+        : 'Enable it with `onboarder start startup install`.')] : []),
+    ]));
+    out('');
+    return status.installed ? 0 : 1;
+  }
+
+  throw new Error('Usage: onboarder start startup [install|remove|status]');
+}
+
 // --------------------------------------------------------------- config ---
 
 // Keys `config set` may touch — the same allow-list the HTTP API enforces, so

package/cli/main.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 
 import {
-  runSetup, runStart, runStatus, runStop, runRestart,
+  runSetup, runStart, runStartBackground, runStartup, runLogs, runStatus, runStop, runRestart,
   runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel, runHttps,
 } from './commands.js';
 
@@ -20,7 +20,10 @@ const HELP = `
   Usage
     onboarder                     Start the server (runs setup first if needed)
     onboarder setup | onboard     Configure interactively (the wizard)
-    onboarder start               Start the server
+    onboarder start               Start in the foreground (Ctrl-C stops it)
+    onboarder start background    Start detached — keeps running after you close the terminal
+    onboarder start startup       Run automatically at login [install|remove|status]
+    onboarder logs                Show recent log lines  (-n <count>, -f to follow)
     onboarder status              Show whether the server is running
     onboarder stop                Stop the running server
     onboarder restart             Stop and start again
@@ -48,11 +51,16 @@ const HELP = `
   Also accepted
     help | --help       onboarder help | onboarder --help
     config | config show
+    bg | detached       alias for start background
+    fg | foreground     alias for start
 
   Examples
     onboarder setup
+    onboarder start background          # leave it running, close the terminal
+    onboarder logs -f                   # watch what it is doing
+    onboarder start startup install     # also start it every time you log in
+    onboarder start background && open http://localhost:4310
     onboarder setup --non-interactive --mode local --port 4310
-    onboarder setup --non-interactive --mode self-hosted --host 0.0.0.0
     onboarder setup --non-interactive --mode self-hosted --domain map.example.com --https --start
     onboarder config set tunnel.cloudflare true && onboarder tunnel cloudflare
 `;
@@ -82,6 +90,9 @@ const OPTIONS = {
   cloudflare: { type: 'boolean' },
   tailscale: { type: 'boolean' },
   'auto-open': { type: 'boolean' },
+  lines: { type: 'string', short: 'n' },
+  follow: { type: 'boolean', short: 'f' },
+  timeout: { type: 'string' },
 };
 
 // parseArgs speaks kebab-case; the wizard's flags speak camelCase.
@@ -115,8 +126,33 @@ export async function main(argv = process.argv.slice(2)) {
         console.log(HELP);
         return 0;
       case undefined:
+        return codeOf(await runStart({ flags }));
       case 'start':
+        // `onboarder start [background|fg|startup [action]]`. The sub-verb is a
+        // positional, not a flag, because `onboarder start` has to keep working
+        // exactly as it did and `startup install` is a different verb from
+        // `start`.
+        if (sub === 'background' || sub === 'bg' || sub === 'daemon' || sub === 'detached') {
+          return codeOf(await runStartBackground({ flags }));
+        }
+        if (sub === 'startup' || sub === 'login' || sub === 'autostart') {
+          return codeOf(await runStartup(rest[0] || 'status', { flags }));
+        }
+        if (sub === 'fg' || sub === 'foreground') return codeOf(await runStart({ flags }));
+        if (sub === 'status') return codeOf(await runStatus({ flags }));
+        if (sub === 'stop') return codeOf(await runStop({ flags }));
+        if (sub === 'logs') return codeOf(await runLogs({ flags }));
+        if (sub) {
+          console.error('  Unknown start mode: ' + sub + '\n' + HELP);
+          return 2;
+        }
         return codeOf(await runStart({ flags }));
+      case 'logs':
+      case 'log':
+        return codeOf(await runLogs({ flags }));
+      case 'startup':
+      case 'autostart':
+        return codeOf(await runStartup(sub || 'status', { flags }));
       case 'status':
         return codeOf(await runStatus({ flags }));
       case 'stop':

package/cli/ui.js

@@ -53,3 +53,21 @@ export function kv(label, value) {
 export const tick = ok('  ✓ ');
 export const cross = bad('  ✗ ');
 export const dash = dim('  – ');
+
+// The layout math (width, fit, panel) lives in `server/layout.js` so the server's
+// own startup banner can use the identical geometry without importing this file
+// and inverting the dependency. This module is only the *color* on top of it.
+import { width, fit, termWidth, panel as layoutPanel, hint, row } from '../server/layout.js';
+
+export { width, fit, termWidth, hint, row };
+
+// A titled block of rows that fits the terminal it is printed into. Same shape
+// the server banner uses; the difference is only that this one paints.
+export function panel(title, rows, options = {}) {
+  const styles = { label: 'gray', frame: 'gray', hint: 'gray', title: 'bold' };
+  return layoutPanel(title, rows, {
+    ...options,
+    paint: (text, style) => paint(text, styles[style] || 'gray'),
+  });
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Drop a path. Get a map. A zero-dependency codebase visualizer with a CLI onboarding wizard, a web UI, and an optional key-gated self-hosted mode.",
   "type": "module",
   "bin": {