ntermqt 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

nterm/scripting/repl.py

@@ -10,7 +10,6 @@
 
 from __future__ import annotations
 
-import os
 import json
 import time
 import shlex
@@ -19,6 +18,11 @@ from datetime import datetime
 from typing import Optional, Dict, Any, List
 
 from .api import NTermAPI, ActiveSession, CommandResult
+from .platform_utils import (
+    get_platform_command,
+    extract_version_info,
+    extract_neighbor_info,
+)
 
 
 @dataclass
@@ -34,16 +38,12 @@ class REPLPolicy:
     def is_allowed(self, command: str) -> bool:
         cmd = command.strip().lower()
 
-        i = 0
-        while i < len(self.deny_substrings):
-            bad = self.deny_substrings[i].lower()
-            if bad in cmd:
+        for bad in self.deny_substrings:
+            if bad.lower() in cmd:
                 return False
-            i += 1
 
         if self.mode == "read_only":
-            # Cheap "write reminder": block common config verbs
-            # (You can tighten to an allow-list only if you want)
+            # Block common config verbs
             write_verbs = [
                 "conf t",
                 "configure",
@@ -62,23 +62,16 @@ class REPLPolicy:
                 "upgrade",
                 "install",
             ]
-            j = 0
-            while j < len(write_verbs):
-                if cmd.startswith(write_verbs[j]):
+            for verb in write_verbs:
+                if cmd.startswith(verb):
                     return False
-                j += 1
 
         # If allow_prefixes provided, require one of them
         if self.allow_prefixes:
-            ok = False
-            k = 0
-            while k < len(self.allow_prefixes):
-                pref = self.allow_prefixes[k].lower()
-                if cmd.startswith(pref):
-                    ok = True
-                    break
-                k += 1
-            return ok
+            for pref in self.allow_prefixes:
+                if cmd.startswith(pref.lower()):
+                    return True
+            return False
 
         return True
 
@@ -101,23 +94,38 @@ class NTermREPL:
     A minimal command router. This is the "tool surface".
     MCP can call `handle_line()`; humans can type into it.
 
-    Commands:
-      :unlock
-      :lock
-      :creds [pattern]
-      :devices [pattern]
-      :connect <device> [--cred name]
-      :disconnect
-      :policy [read_only|ops]
-      :mode [raw|parsed]
-      :format [text|rich|json]
-      :set_hint <platform>
-      :clear_hint
-      :debug [on|off]
-      :dbinfo
-      (anything else runs as CLI on the connected session)
-      :help
-      :exit
+    Meta Commands:
+      :unlock              Unlock credential vault (prompts for password)
+      :lock                Lock credential vault
+      :creds [pattern]     List credentials
+      :devices [pattern]   List devices
+      :folders             List folders
+      :connect <device>    Connect to device [--cred name] [--debug]
+      :disconnect          Disconnect current session
+      :disconnect_all      Disconnect all sessions
+      :switch <device>     Switch to another active session
+      :sessions            List all active sessions
+      :policy [mode]       Get/set policy (read_only|ops)
+      :mode [raw|parsed]   Get/set output mode
+      :format [fmt]        Get/set format (text|rich|json)
+      :set_hint <platform> Override platform detection
+      :clear_hint          Use auto-detected platform
+      :debug [on|off]      Toggle debug mode
+      :dbinfo              Show TextFSM database info
+      :help                Show help
+      :exit                Disconnect and exit
+
+    Quick Commands (platform-aware):
+      :config              Fetch running config
+      :version             Fetch and parse version info
+      :interfaces          Fetch interface status
+      :neighbors           Fetch CDP/LLDP neighbors (tries both)
+      :bgp                 Fetch BGP summary
+      :routes              Fetch routing table
+      :intf <n>         Fetch specific interface details
+
+    Raw Commands:
+      (anything else)      Runs as CLI on the connected session
     """
 
     def __init__(self, api: Optional[NTermAPI] = None, policy: Optional[REPLPolicy] = None):
@@ -127,7 +135,7 @@ class NTermREPL:
             policy = REPLPolicy(
                 mode="read_only",
                 deny_substrings=[
-                    "terminal monitor",  # example if you don't want interactive spam
+                    "terminal monitor",  # Don't want interactive spam
                 ],
                 allow_prefixes=[],
             )
@@ -153,16 +161,19 @@ class NTermREPL:
         parts = shlex.split(line)
         cmd = parts[0].lower()
 
+        # ===== Help & Exit =====
         if cmd == ":help":
             return self._ok({"type": "help", "text": self._help_text()})
 
         if cmd == ":exit":
-            if self.state.session:
-                self._safe_disconnect()
-            return self._ok({"type": "exit"})
+            # Use disconnect_all for clean shutdown
+            count = self.state.api.disconnect_all()
+            self.state.session = None
+            self.state.connected_device = None
+            return self._ok({"type": "exit", "disconnected": count})
 
+        # ===== Vault Commands =====
         if cmd == ":unlock":
-            # Password should be provided separately, not in the command line
             if len(parts) > 1:
                 return self._err(":unlock takes no arguments. Password will be prompted securely.")
             return self._ok({"type": "unlock_prompt", "message": "Please provide vault password"})
@@ -172,63 +183,80 @@ class NTermREPL:
             self.state.vault_unlocked = False
             return self._ok({"type": "lock", "vault_unlocked": False})
 
+        # ===== Inventory Commands =====
         if cmd == ":creds":
             if not self.state.api.vault_unlocked:
-                return self._err("Vault is locked. Run :unlock <password> first.")
-
-            pattern = None
-            if len(parts) >= 2:
-                pattern = parts[1]
+                return self._err("Vault is locked. Run :unlock first.")
 
+            pattern = parts[1] if len(parts) >= 2 else None
             creds = self.state.api.credentials(pattern=pattern)
-            rows: List[Dict[str, Any]] = []
-            i = 0
-            while i < len(creds):
-                rows.append(creds[i].to_dict())
-                i += 1
+            rows = [c.to_dict() for c in creds]
             return self._ok({"type": "credentials", "credentials": rows})
 
         if cmd == ":devices":
-            pattern = None
-            if len(parts) >= 2:
-                pattern = parts[1]
-            devs = self.state.api.devices(pattern=pattern)
-            # No comprehensions
-            rows: List[Dict[str, Any]] = []
-            i = 0
-            while i < len(devs):
-                rows.append(devs[i].to_dict())
-                i += 1
+            pattern = parts[1] if len(parts) >= 2 else None
+            folder = None
+
+            # Check for --folder flag
+            for i, p in enumerate(parts):
+                if p == "--folder" and i + 1 < len(parts):
+                    folder = parts[i + 1]
+                    break
+
+            devs = self.state.api.devices(pattern=pattern, folder=folder)
+            rows = [d.to_dict() for d in devs]
             return self._ok({"type": "devices", "devices": rows})
 
+        if cmd == ":folders":
+            folders = self.state.api.folders()
+            return self._ok({"type": "folders", "folders": folders})
+
+        # ===== Session Commands =====
         if cmd == ":connect":
             if len(parts) < 2:
-                return self._err("Usage: :connect <device> [--cred name]")
+                return self._err("Usage: :connect <device> [--cred name] [--debug]")
 
             device = parts[1]
             cred = None
+            debug = self.state.debug_mode
 
             i = 2
             while i < len(parts):
-                if parts[i] == "--cred":
-                    if i + 1 < len(parts):
-                        cred = parts[i + 1]
-                        i += 1
-                i += 1
+                if parts[i] == "--cred" and i + 1 < len(parts):
+                    cred = parts[i + 1]
+                    i += 2
+                elif parts[i] == "--debug":
+                    debug = True
+                    i += 1
+                else:
+                    i += 1
 
             if not self.state.api.vault_unlocked:
-                return self._err("Vault is locked. Run :unlock <password> first.")
-
-            if self.state.session:
-                self._safe_disconnect()
+                return self._err("Vault is locked. Run :unlock first.")
+
+            # Check if already connected to this device
+            existing_sessions = self.state.api.active_sessions()
+            for sess in existing_sessions:
+                if sess.device_name == device:
+                    # Already connected - just switch to it
+                    self.state.session = sess
+                    self.state.connected_device = sess.device_name
+                    return self._ok({
+                        "type": "switch",
+                        "device": sess.device_name,
+                        "hostname": sess.hostname,
+                        "port": sess.port,
+                        "platform": sess.platform,
+                        "prompt": sess.prompt,
+                        "message": "Already connected - switched to existing session",
+                    })
+
+            # NOTE: We no longer disconnect the existing session!
+            # Old sessions stay active in the background.
+            # User can switch back with :switch or disconnect with :disconnect
 
             try:
-                # Pass debug flag from REPL state
-                sess = self.state.api.connect(
-                    device,
-                    credential=cred,
-                    debug=self.state.debug_mode  # <-- This line
-                )
+                sess = self.state.api.connect(device, credential=cred, debug=debug)
                 self.state.session = sess
                 self.state.connected_device = sess.device_name
 
@@ -244,9 +272,82 @@ class NTermREPL:
                 return self._err(f"Connection failed: {e}")
 
         if cmd == ":disconnect":
+            if not self.state.session:
+                return self._ok({"type": "disconnect", "message": "No active session"})
+
+            device_name = self.state.connected_device
             self._safe_disconnect()
-            return self._ok({"type": "disconnect"})
 
+            # Try to switch to another active session if available
+            remaining = self.state.api.active_sessions()
+            if remaining:
+                self.state.session = remaining[0]
+                self.state.connected_device = remaining[0].device_name
+                return self._ok({
+                    "type": "disconnect",
+                    "disconnected": device_name,
+                    "switched_to": self.state.connected_device,
+                    "message": f"Disconnected {device_name}, switched to {self.state.connected_device}",
+                })
+
+            return self._ok({"type": "disconnect", "disconnected": device_name})
+
+        if cmd == ":disconnect_all":
+            count = self.state.api.disconnect_all()
+            self.state.session = None
+            self.state.connected_device = None
+            return self._ok({"type": "disconnect_all", "count": count})
+
+        if cmd == ":switch":
+            if len(parts) < 2:
+                # Show available sessions
+                sessions = self.state.api.active_sessions()
+                if not sessions:
+                    return self._err("No active sessions. Use :connect <device> first.")
+
+                session_names = [s.device_name for s in sessions]
+                return self._err(f"Usage: :switch <device>\nActive sessions: {', '.join(session_names)}")
+
+            target_device = parts[1]
+
+            # Find the session
+            sessions = self.state.api.active_sessions()
+            for sess in sessions:
+                if sess.device_name == target_device:
+                    self.state.session = sess
+                    self.state.connected_device = sess.device_name
+                    return self._ok({
+                        "type": "switch",
+                        "device": sess.device_name,
+                        "hostname": sess.hostname,
+                        "port": sess.port,
+                        "platform": sess.platform,
+                        "prompt": sess.prompt,
+                    })
+
+            # Not found
+            session_names = [s.device_name for s in sessions]
+            return self._err(f"Session '{target_device}' not found.\nActive sessions: {', '.join(session_names)}")
+
+        if cmd == ":sessions":
+            sessions = self.state.api.active_sessions()
+            rows = []
+            for s in sessions:
+                rows.append({
+                    "device": s.device_name,
+                    "hostname": s.hostname,
+                    "port": s.port,
+                    "platform": s.platform,
+                    "prompt": s.prompt,
+                    "connected": s.is_connected(),
+                })
+            return self._ok({
+                "type": "sessions",
+                "sessions": rows,
+                "current": self.state.connected_device,
+            })
+
+        # ===== Settings Commands =====
         if cmd == ":policy":
             if len(parts) < 2:
                 return self._ok({"type": "policy", "mode": self.state.policy.mode})
@@ -265,56 +366,308 @@ class NTermREPL:
                 })
             mode = parts[1].lower()
             if mode not in ["raw", "parsed"]:
-                return self._err("Mode must be 'raw' or 'parsed'")
+                return self._err("Mode must be raw or parsed")
             self.state.output_mode = mode
             return self._ok({"type": "mode", "mode": mode})
 
         if cmd == ":format":
             if len(parts) < 2:
-                return self._ok({
-                    "type": "format",
-                    "format": self.state.output_format,
-                })
+                return self._ok({"type": "format", "format": self.state.output_format})
             fmt = parts[1].lower()
             if fmt not in ["text", "rich", "json"]:
-                return self._err("Format must be 'text', 'rich', or 'json'")
+                return self._err("Format must be text, rich, or json")
             self.state.output_format = fmt
             return self._ok({"type": "format", "format": fmt})
 
         if cmd == ":set_hint":
             if len(parts) < 2:
                 return self._err("Usage: :set_hint <platform> (e.g., cisco_ios, arista_eos)")
-            platform = parts[1].lower()
-            self.state.platform_hint = platform
-            return self._ok({"type": "set_hint", "platform_hint": platform})
+            self.state.platform_hint = parts[1]
+            return self._ok({"type": "set_hint", "platform_hint": self.state.platform_hint})
 
         if cmd == ":clear_hint":
             self.state.platform_hint = None
             return self._ok({"type": "clear_hint"})
 
         if cmd == ":debug":
-            if len(parts) >= 2:
-                mode = parts[1].lower()
-                if mode in ["on", "true", "1"]:
-                    self.state.debug_mode = True
-                elif mode in ["off", "false", "0"]:
-                    self.state.debug_mode = False
-                else:
-                    return self._err("Debug mode must be on or off")
-            else:
-                # Toggle
-                self.state.debug_mode = not self.state.debug_mode
+            if len(parts) < 2:
+                return self._ok({"type": "debug", "debug_mode": self.state.debug_mode})
+            val = parts[1].lower()
+            self.state.debug_mode = val in ["on", "true", "1", "yes"]
             return self._ok({"type": "debug", "debug_mode": self.state.debug_mode})
 
         if cmd == ":dbinfo":
-            try:
-                db_info = self.state.api.db_info()
-                return self._ok({"type": "dbinfo", "db_info": db_info})
-            except Exception as e:
-                return self._err(f"Failed to get DB info: {e}")
+            info = self.state.api.db_info()
+            return self._ok({"type": "dbinfo", "db_info": info})
+
+        # ===== Quick Commands =====
+        if cmd == ":config":
+            return self._quick_config()
+
+        if cmd == ":version":
+            return self._quick_version()
+
+        if cmd == ":interfaces":
+            return self._quick_interfaces()
+
+        if cmd == ":neighbors":
+            return self._quick_neighbors()
+
+        if cmd == ":bgp":
+            return self._quick_bgp()
+
+        if cmd == ":routes":
+            return self._quick_routes()
+
+        if cmd == ":intf":
+            if len(parts) < 2:
+                return self._err("Usage: :intf <interface> (e.g., :intf Gi0/1)")
+            return self._quick_interface_detail(parts[1])
 
         return self._err(f"Unknown REPL command: {cmd}")
 
+    # -----------------------
+    # Quick commands
+    # -----------------------
+
+    def _quick_config(self) -> Dict[str, Any]:
+        """Fetch running configuration."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_platform_command(
+                self.state.session,
+                'config',
+                parse=False,  # Config is typically not parsed
+                timeout=60,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                return self._err("Config command not available for this platform")
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "config"
+
+            return self._ok({"type": "config", "result": payload})
+
+        except Exception as e:
+            return self._err(f"Config fetch failed: {e}")
+
+    def _quick_version(self) -> Dict[str, Any]:
+        """Fetch and extract version info."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_platform_command(
+                self.state.session,
+                'version',
+                parse=True,
+                timeout=30,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                return self._err("Version command not available for this platform")
+
+            # Extract structured version info
+            version_info = extract_version_info(
+                result.parsed_data,
+                self.state.platform_hint or self.state.session.platform
+            )
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "version"
+            payload["version_info"] = version_info
+
+            return self._ok({"type": "version", "result": payload})
+
+        except Exception as e:
+            return self._err(f"Version command failed: {e}")
+
+    def _quick_interfaces(self) -> Dict[str, Any]:
+        """Fetch interface status."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_platform_command(
+                self.state.session,
+                'interfaces_status',
+                parse=True,
+                timeout=30,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                return self._err("Interfaces command not available for this platform")
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "interfaces"
+
+            return self._ok({"type": "interfaces", "result": payload})
+
+        except Exception as e:
+            return self._err(f"Interfaces command failed: {e}")
+
+    def _quick_neighbors(self) -> Dict[str, Any]:
+        """Fetch CDP/LLDP neighbors with fallback."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        platform = self.state.platform_hint or self.state.session.platform
+
+        # Build command list - CDP first for Cisco, LLDP first for others
+        cdp_cmd = get_platform_command(platform, 'neighbors_cdp')
+        lldp_cmd = get_platform_command(platform, 'neighbors_lldp')
+
+        if platform and 'cisco' in platform:
+            commands = [cdp_cmd, lldp_cmd]
+        else:
+            commands = [lldp_cmd, cdp_cmd]
+
+        # Filter None commands
+        commands = [c for c in commands if c]
+
+        if not commands:
+            return self._err(f"No neighbor discovery commands available for platform '{platform}'")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_first(
+                self.state.session,
+                commands,
+                parse=True,
+                timeout=30,
+                require_parsed=True,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                # Try without requiring parsed data
+                result = self.state.api.send_first(
+                    self.state.session,
+                    commands,
+                    parse=True,
+                    timeout=30,
+                    require_parsed=False,
+                )
+
+            if not result:
+                return self._ok({
+                    "type": "neighbors",
+                    "result": {
+                        "command": "CDP/LLDP",
+                        "raw_output": "No neighbors found or commands failed",
+                        "parsed_data": [],
+                        "elapsed_seconds": round(elapsed, 3),
+                    }
+                })
+
+            # Extract normalized neighbor info
+            neighbors = extract_neighbor_info(result.parsed_data) if result.parsed_data else []
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "neighbors"
+            payload["neighbor_info"] = neighbors
+
+            return self._ok({"type": "neighbors", "result": payload})
+
+        except Exception as e:
+            return self._err(f"Neighbor discovery failed: {e}")
+
+    def _quick_bgp(self) -> Dict[str, Any]:
+        """Fetch BGP summary."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_platform_command(
+                self.state.session,
+                'bgp_summary',
+                parse=True,
+                timeout=30,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                return self._err("BGP command not available for this platform")
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "bgp"
+
+            return self._ok({"type": "bgp", "result": payload})
+
+        except Exception as e:
+            return self._err(f"BGP command failed: {e}")
+
+    def _quick_routes(self) -> Dict[str, Any]:
+        """Fetch routing table."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_platform_command(
+                self.state.session,
+                'routing_table',
+                parse=True,
+                timeout=30,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                return self._err("Routing command not available for this platform")
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "routes"
+
+            return self._ok({"type": "routes", "result": payload})
+
+        except Exception as e:
+            return self._err(f"Routing command failed: {e}")
+
+    def _quick_interface_detail(self, interface: str) -> Dict[str, Any]:
+        """Fetch specific interface details."""
+        if not self.state.session:
+            return self._err("Not connected. Use :connect <device>")
+
+        try:
+            started = time.time()
+            result = self.state.api.send_platform_command(
+                self.state.session,
+                'interface_detail',
+                name=interface,
+                parse=True,
+                timeout=30,
+            )
+            elapsed = time.time() - started
+
+            if not result:
+                return self._err(f"Interface detail command not available for this platform")
+
+            payload = result.to_dict()
+            payload["elapsed_seconds"] = round(elapsed, 3)
+            payload["command_type"] = "interface_detail"
+            payload["interface"] = interface
+
+            return self._ok({"type": "interface_detail", "result": payload})
+
+        except Exception as e:
+            return self._err(f"Interface detail command failed: {e}")
+
     # -----------------------
     # CLI send path
     # -----------------------
@@ -328,15 +681,15 @@ class NTermREPL:
 
         try:
             started = time.time()
-            
+
             # Determine if we should parse based on output mode
             should_parse = (self.state.output_mode == "parsed")
-            
-            # Apply platform hint if set (modify session platform temporarily)
+
+            # Apply platform hint if set
             original_platform = self.state.session.platform
             if self.state.platform_hint:
                 self.state.session.platform = self.state.platform_hint
-            
+
             try:
                 res: CommandResult = self.state.api.send(
                     self.state.session,
@@ -349,13 +702,13 @@ class NTermREPL:
                 # Restore original platform
                 if self.state.platform_hint:
                     self.state.session.platform = original_platform
-                    
+
             elapsed = time.time() - started
 
             # Clip raw output for safety/transport
             raw = res.raw_output or ""
             if len(raw) > self.state.policy.max_output_chars:
-                raw = raw[: self.state.policy.max_output_chars] + "\n...<truncated>..."
+                raw = raw[:self.state.policy.max_output_chars] + "\n...<truncated>..."
 
             payload = res.to_dict()
             payload["raw_output"] = raw
@@ -365,13 +718,18 @@ class NTermREPL:
         except Exception as e:
             return self._err(f"Command execution failed: {e}")
 
+    # -----------------------
+    # Helpers
+    # -----------------------
+
     def _safe_disconnect(self) -> None:
+        """Disconnect current session only (not all sessions)."""
         if self.state.session:
             try:
                 self.state.api.disconnect(self.state.session)
             finally:
                 self.state.session = None
-                self.connected_device = None
+                self.state.connected_device = None
 
     def do_unlock(self, password: str) -> Dict[str, Any]:
         """Internal method to perform unlock with password."""
@@ -383,25 +741,63 @@ class NTermREPL:
             return self._err(f"Unlock failed: {e}")
 
     def _help_text(self) -> str:
-        return (
-            "Commands:\n"
-            "  :unlock             (prompts for vault password securely)\n"
-            "  :lock\n"
-            "  :creds [pattern]\n"
-            "  :devices [pattern]\n"
-            "  :connect <device> [--cred name]\n"
-            "  :disconnect\n"
-            "  :policy [read_only|ops]\n"
-            "  :mode [raw|parsed]  (control output format, default: parsed)\n"
-            "  :format [text|rich|json] (parsed mode display format, default: text)\n"
-            "  :set_hint <platform> (override TextFSM platform, e.g., cisco_ios)\n"
-            "  :clear_hint         (use auto-detected platform)\n"
-            "  :debug [on|off]     (show full result data for troubleshooting)\n"
-            "  :dbinfo             (show TextFSM database status)\n"
-            "  (anything else runs as CLI on the connected session)\n"
-            "  :help\n"
-            "  :exit\n"
-        )
+        return """
+nterm REPL Commands
+===================
+
+Vault:
+  :unlock              Unlock credential vault (prompts securely)
+  :lock                Lock credential vault
+
+Inventory:
+  :creds [pattern]     List credentials (supports glob patterns)
+  :devices [pattern]   List devices [--folder name]
+  :folders             List all folders
+
+Sessions:
+  :connect <device>    Connect to device [--cred name] [--debug]
+  :disconnect          Disconnect current session
+  :disconnect_all      Disconnect all sessions
+  :switch <device>     Switch to another active session
+  :sessions            List all active sessions
+
+Quick Commands (platform-aware, auto-selects correct syntax):
+  :config              Fetch running configuration
+  :version             Fetch and parse version info
+  :interfaces          Fetch interface status
+  :neighbors           Fetch CDP/LLDP neighbors (tries both)
+  :bgp                 Fetch BGP summary
+  :routes              Fetch routing table
+  :intf <n>            Fetch specific interface details
+
+Settings:
+  :policy [mode]       Get/set policy mode (read_only|ops)
+  :mode [raw|parsed]   Get/set output mode
+  :format [fmt]        Get/set display format (text|rich|json)
+  :set_hint <platform> Override platform detection (cisco_ios, arista_eos, etc.)
+  :clear_hint          Use auto-detected platform
+  :debug [on|off]      Toggle debug mode
+
+Info:
+  :dbinfo              Show TextFSM database status
+  :help                Show this help
+  :exit                Disconnect all and exit
+
+Raw Commands:
+  (anything else)      Sends as CLI command to connected device
+
+Multi-Session Example:
+  :connect spine-1     # Connect to first device
+  show version         # Run command on spine-1
+  :connect spine-2     # Connect to second (spine-1 stays active!)
+  show version         # Run command on spine-2
+  :sessions            # See both sessions
+  :switch spine-1      # Switch back to spine-1
+  show ip route        # Run command on spine-1
+  :disconnect          # Disconnect spine-1, auto-switch to spine-2
+  :disconnect_all      # Disconnect all remaining sessions
+  :exit
+"""
 
     def _ok(self, data: Dict[str, Any]) -> Dict[str, Any]:
         return {"ok": True, "data": data, "ts": datetime.now().isoformat()}