feat(cli): add attach alias, improve empty-session messages, add startup hints (#119)

Improves the CLI experience for session management. Adds `termbeam
attach` as a non-breaking alias for `termbeam resume` to match
tmux/docker conventions. Shows the server URL in empty-session messages
so users can tell the server is reachable. Adds next-step hints after
server and service startup showing available commands.

Closes #118

---------

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

Author: dorlugasigal

bin/termbeam.js

@@ -8,7 +8,7 @@ if (subcommand === 'service') {
     console.error(err.message);
     process.exit(1);
   });
-} else if (subcommand === 'resume') {
+} else if (subcommand === 'resume' || subcommand === 'attach') {
   const { resume } = require('../src/resume');
   resume(process.argv.slice(3)).catch((err) => {
     console.error(err.message);
@@ -129,7 +129,7 @@ if (subcommand === 'service') {
         const displayHost = existing.host === '127.0.0.1' ? 'localhost' : existing.host;
         console.error(
           `TermBeam is already running on http://${displayHost}:${existing.port}\n` +
-            'Use "termbeam resume" to reconnect, "termbeam list" to list sessions,\n' +
+            'Use "termbeam resume" (or "termbeam attach") to reconnect, "termbeam list" to list sessions,\n' +
             'or "termbeam --force" to stop the existing server and start a new one.',
         );
         process.exit(1);

docs/architecture.md

@@ -161,7 +161,7 @@ WebSocket terminal client used by the `resume` command. Handles raw-mode stdin/s
 
 ### `resume.js` — Resume & List Subcommands
 
-Implements the `termbeam resume [name]` and `termbeam list` CLI subcommands. Auto-discovers running servers via `~/.termbeam/connection.json`, lists sessions, provides an interactive arrow-key chooser when multiple sessions exist, and delegates terminal attachment to `client.js`.
+Implements the `termbeam resume [name]` (alias: `termbeam attach`) and `termbeam list` CLI subcommands. Auto-discovers running servers via `~/.termbeam/connection.json`, lists sessions, provides an interactive arrow-key chooser when multiple sessions exist, and delegates terminal attachment to `client.js`.
 
 ---
 

docs/resume.md

@@ -10,6 +10,8 @@ termbeam list
 
 # Reconnect to a running session (interactive chooser if multiple)
 termbeam resume
+# or equivalently:
+termbeam attach
 
 # Reconnect by session name
 termbeam resume my-project
@@ -18,14 +20,15 @@ termbeam resume my-project
 # Press Ctrl+B
 ```
 
-## `termbeam resume`
+## `termbeam resume` (alias: `termbeam attach`)
 
 Connects to a running TermBeam server and attaches to a session via WebSocket, piping your terminal's stdin/stdout directly. The experience is identical to working in the original terminal.
 
 ### Usage
 
 ```
 termbeam resume [name] [options]
+termbeam attach [name] [options]   # alias
 ```
 
 ### Arguments
@@ -97,7 +100,7 @@ When a TermBeam server starts, it saves connection details to `~/.termbeam/conne
 }
 ```
 
-The `resume` and `list` commands read this file automatically, so you don't need to remember or type the port and password. The file is removed when the server shuts down.
+The `resume` (or `attach`) and `list` commands read this file automatically, so you don't need to remember or type the port and password. The file is removed when the server shuts down.
 
 <!-- prettier-ignore -->
 !!! note "Multiple servers"

package-lock.json

@@ -10,7 +10,7 @@ termbeam — Beam your terminal to any device
 
 Usage:
   termbeam [options] [shell] [args...]
-  termbeam resume [name] [options]     Reconnect to a running session
+  termbeam resume [name] [options]     Reconnect to a running session (alias: attach)
   termbeam list                        List running sessions
   termbeam service <action>            Manage as a background service (PM2)
 
@@ -54,6 +54,7 @@ Examples:
   termbeam --interactive               Guided setup wizard
   termbeam service install          Set up as background service (PM2)
   termbeam resume                   Reconnect to an active session
+  termbeam attach my-session        Attach to a named session (alias for resume)
   termbeam list                     List all active sessions
 
 Environment:

src/cli.js

@@ -155,7 +155,7 @@ function detachKeyLabel(key) {
 
 function printResumeHelp() {
   console.log(`
-${bold('termbeam resume')} — Reconnect to a running session
+${bold('termbeam resume')} (alias: ${bold('attach')}) — Reconnect to a running session
 
 ${bold('Usage:')}
   termbeam resume [name] [options]
@@ -243,7 +243,7 @@ async function resume(args) {
   const { host, port, password, sessions, opts } = conn;
 
   if (sessions.length === 0) {
-    console.error(red('  No active sessions on the server.'));
+    console.error(red(`  Connected to server on ${conn.displayUrl} — no active sessions.`));
     process.exit(1);
   }
 
@@ -345,7 +345,7 @@ async function list() {
   }
 
   if (sessions.length === 0) {
-    console.log(dim('  No active sessions.'));
+    console.log(dim(`  Connected to server on ${displayUrl} — no active sessions.`));
     return;
   }
 

src/resume.js

@@ -266,6 +266,12 @@ function createTermBeamServer(overrides = {}) {
         console.log(`  Scan the QR code or open: ${bl}${qrDisplayUrl}${rs}`);
         if (config.password) process.stdout.write(`  Password: ${gn}${config.password}${rs}\n`);
         console.log('');
+        console.log(`${_dm}  From another terminal:${rs}`);
+        console.log(`${_dm}    termbeam list        List active sessions${rs}`);
+        console.log(
+          `${_dm}    termbeam resume      Attach to a session (or: termbeam attach)${rs}`,
+        );
+        console.log('');
 
         resolve({ url: `http://localhost:${actualPort}`, defaultId });
       });

src/server.js

@@ -460,9 +460,13 @@ async function actionInstall() {
   }
 
   console.log(dim('\nUseful commands:'));
-  console.log(`  ${cyan('termbeam service status')}   — Check service status`);
-  console.log(`  ${cyan('termbeam service logs')}     — View logs`);
-  console.log(`  ${cyan('termbeam service restart')}  — Restart service`);
+  console.log(`  ${cyan('termbeam list')}              — List active sessions`);
+  console.log(
+    `  ${cyan('termbeam resume')}            — Attach to a session (or: termbeam attach)`,
+  );
+  console.log(`  ${cyan('termbeam service status')}    — Check service status`);
+  console.log(`  ${cyan('termbeam service logs')}      — View logs`);
+  console.log(`  ${cyan('termbeam service restart')}   — Restart service`);
   console.log(`  ${cyan('termbeam service uninstall')} — Remove service\n`);
 }
 

src/service.js

@@ -873,7 +873,7 @@ describe('resume', () => {
         reloadResume();
 
         await resume.list();
-        // Should print "No active sessions." and return
+        // Should print "Connected to server on ... — no active sessions." and return
       });
 
       it('should display singular "session" when count is 1', async () => {