remote-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{remote_cli-0.1.0 → remote_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: remote-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: A shared SSH CLI tool for AI Agent and human co-piloting
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -12,6 +12,10 @@ Description-Content-Type: text/markdown
 
 # remote-cli
 
+<p align="center">
+  <img src="assets/remote_cli_ai_poster.png" alt="remote-cli Poster" width="600">
+</p>
+
 > **Shared SSH & Terminal CLI tool for AI Agent and Human Co-piloting.**
 
 `remote-cli` allows a human user to start an interactive SSH session (handling passwords, 2FA, bastion hosts, and SSH keys themselves) and share that session with an AI Agent via a unique `session-id`.
@@ -105,13 +109,17 @@ uv run remote-cli send s_7f8a9b2c "y"
 
 # Agent sends Ctrl+C to interrupt a long-running process
 uv run remote-cli send s_7f8a9b2c --ctrl-c
+
+# Agent transfers files or directories (like docker cp)
+uv run remote-cli cp ./app.tar.gz s_7f8a9b2c:/opt/
+uv run remote-cli cp s_7f8a9b2c:/var/log/nginx/error.log ./logs/
 ```
 
 ---
 
 ### 3. Human Observation & Intervention
 
-While the Agent is executing commands, the human user sees all command text and outputs scrolling in real time in their terminal window. If needed, the human can type commands directly into that same terminal window.
+While the Agent is executing commands or transferring files, the human user sees all command text and outputs scrolling in real time in their terminal window. If needed, the human can type commands directly into that same terminal window.
 
 ---
 
@@ -125,11 +133,15 @@ While the Agent is executing commands, the human user sees all command text and
 | `remote-cli session attach <ID>` (or `attach`) | Attach terminal in raw mode to existing session |
 | `remote-cli session close <ID>` | Close and terminate a session |
 | `remote-cli exec <ID> "<COMMAND>"` | Execute command in session, capture output & exit code |
+| `remote-cli cp <SRC> <DEST>` | Transfer files/dirs between local & session (`./file s_xxx:/remote/`) |
+| `remote-cli upload <ID> <LOCAL> <REMOTE>` | Upload local file or directory to remote session |
+| `remote-cli download <ID> <REMOTE> <LOCAL>` | Download remote file or directory from session to local |
 | `remote-cli send <ID> [TEXT]` | Send raw keystrokes or control keys (`--ctrl-c`, `--ctrl-d`) |
 | `remote-cli snapshot <ID>` | Capture 2D terminal screen state (ANSI-rendered) |
 | `remote-cli logs <ID> [-n LINES]` | View recent output scrollback logs |
 | `remote-cli daemon start / stop / status` | Manage background daemon lifecycle |
 
+
 ---
 
 ## Architecture
@@ -149,14 +161,19 @@ While the Agent is executing commands, the human user sees all command text and
    │  ┌────────────────────────────────────────────────────────┐ │
    │  │ Session (e.g. s_7f8a9b2c)                              │ │
    │  │  - Master/Slave PTY (`pty.openpty`)                    │ │
+   │  │  - SSH ControlMaster Socket (`~/.remote-cli/cm/*.sock`) │ │
    │  │  - Pyte Virtual Terminal Screen (`pyte.HistoryScreen`) │ │
    │  │  - Scrollback Ring Buffer                              │ │
    │  │  - Exec Sentinel Detection Engine                      │ │
+   │  │  - Dual Transfer Engine:                               │ │
+   │  │     * Fast Path: Native OpenSSH ControlMaster SCP      │ │
+   │  │     * Fallback: Universal In-Band Tar+Base64 Stream    │ │
    │  │  - Process: `ssh user@remote-server` (or local shell)  │ │
    │  └────────────────────────────────────────────────────────┘ │
    └─────────────────────────────────────────────────────────────┘
 ```
 
+
 ---
 
 ## Running Tests

{remote_cli-0.1.0 → remote_cli-0.2.0}/README.md

@@ -1,5 +1,9 @@
 # remote-cli
 
+<p align="center">
+  <img src="assets/remote_cli_ai_poster.png" alt="remote-cli Poster" width="600">
+</p>
+
 > **Shared SSH & Terminal CLI tool for AI Agent and Human Co-piloting.**
 
 `remote-cli` allows a human user to start an interactive SSH session (handling passwords, 2FA, bastion hosts, and SSH keys themselves) and share that session with an AI Agent via a unique `session-id`.
@@ -93,13 +97,17 @@ uv run remote-cli send s_7f8a9b2c "y"
 
 # Agent sends Ctrl+C to interrupt a long-running process
 uv run remote-cli send s_7f8a9b2c --ctrl-c
+
+# Agent transfers files or directories (like docker cp)
+uv run remote-cli cp ./app.tar.gz s_7f8a9b2c:/opt/
+uv run remote-cli cp s_7f8a9b2c:/var/log/nginx/error.log ./logs/
 ```
 
 ---
 
 ### 3. Human Observation & Intervention
 
-While the Agent is executing commands, the human user sees all command text and outputs scrolling in real time in their terminal window. If needed, the human can type commands directly into that same terminal window.
+While the Agent is executing commands or transferring files, the human user sees all command text and outputs scrolling in real time in their terminal window. If needed, the human can type commands directly into that same terminal window.
 
 ---
 
@@ -113,11 +121,15 @@ While the Agent is executing commands, the human user sees all command text and
 | `remote-cli session attach <ID>` (or `attach`) | Attach terminal in raw mode to existing session |
 | `remote-cli session close <ID>` | Close and terminate a session |
 | `remote-cli exec <ID> "<COMMAND>"` | Execute command in session, capture output & exit code |
+| `remote-cli cp <SRC> <DEST>` | Transfer files/dirs between local & session (`./file s_xxx:/remote/`) |
+| `remote-cli upload <ID> <LOCAL> <REMOTE>` | Upload local file or directory to remote session |
+| `remote-cli download <ID> <REMOTE> <LOCAL>` | Download remote file or directory from session to local |
 | `remote-cli send <ID> [TEXT]` | Send raw keystrokes or control keys (`--ctrl-c`, `--ctrl-d`) |
 | `remote-cli snapshot <ID>` | Capture 2D terminal screen state (ANSI-rendered) |
 | `remote-cli logs <ID> [-n LINES]` | View recent output scrollback logs |
 | `remote-cli daemon start / stop / status` | Manage background daemon lifecycle |
 
+
 ---
 
 ## Architecture
@@ -137,14 +149,19 @@ While the Agent is executing commands, the human user sees all command text and
    │  ┌────────────────────────────────────────────────────────┐ │
    │  │ Session (e.g. s_7f8a9b2c)                              │ │
    │  │  - Master/Slave PTY (`pty.openpty`)                    │ │
+   │  │  - SSH ControlMaster Socket (`~/.remote-cli/cm/*.sock`) │ │
    │  │  - Pyte Virtual Terminal Screen (`pyte.HistoryScreen`) │ │
    │  │  - Scrollback Ring Buffer                              │ │
    │  │  - Exec Sentinel Detection Engine                      │ │
+   │  │  - Dual Transfer Engine:                               │ │
+   │  │     * Fast Path: Native OpenSSH ControlMaster SCP      │ │
+   │  │     * Fallback: Universal In-Band Tar+Base64 Stream    │ │
    │  │  - Process: `ssh user@remote-server` (or local shell)  │ │
    │  └────────────────────────────────────────────────────────┘ │
    └─────────────────────────────────────────────────────────────┘
 ```
 
+
 ---
 
 ## Running Tests

{remote_cli-0.1.0 → remote_cli-0.2.0}/skills/remote-cli/SKILL.md

@@ -126,7 +126,28 @@ remote-cli logs <session-id> --lines 50
 
 ---
 
-### 3.5. List Active Sessions (`remote-cli session list` / `remote-cli ls`)
+### 3.5. Transfer Files & Directories (`remote-cli cp` / `upload` / `download`)
+
+Seamlessly transfers files and directories between the local machine and the remote server over the active session without requiring SFTP configuration or opening extra ports.
+
+```bash
+# Docker-style copy syntax:
+# Upload local file/dir to remote server:
+remote-cli cp ./dist/app.tar.gz <session-id>:/opt/app/
+remote-cli cp ./config/ <session-id>:/opt/config/
+
+# Download remote file/dir to local machine:
+remote-cli cp <session-id>:/var/log/nginx/error.log ./logs/
+remote-cli cp <session-id>:/var/log/nginx/ ./local_nginx_logs/
+
+# Direct upload/download commands:
+remote-cli upload <session-id> <local-path> <remote-path>
+remote-cli download <session-id> <remote-path> <local-path>
+```
+
+---
+
+### 3.6. List Active Sessions (`remote-cli session list` / `remote-cli ls`)
 
 Discovers active and recent sessions.
 
@@ -134,6 +155,7 @@ Discovers active and recent sessions.
 remote-cli ls
 ```
 
+
 ---
 
 ## 4. Agent Guidelines & Best Practices

{remote_cli-0.1.0 → remote_cli-0.2.0}/src/remote_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

{remote_cli-0.1.0 → remote_cli-0.2.0}/src/remote_cli/cli.py

@@ -134,10 +134,21 @@ def session_list():
 
 
 @session_app.command("attach")
-def session_attach(session_id: str):
-    """Attach terminal to an existing session."""
+def session_attach(
+    session_id: str | None = typer.Argument(
+        None, help="Target session ID (defaults to latest active session)"
+    ),
+):
+    """Attach terminal to an existing session (like tmux attach)."""
     ensure_daemon_running()
     client = Client()
+    if not session_id:
+        active_sessions = [s for s in client.list_sessions() if s.status == "active"]
+        if not active_sessions:
+            err_console.print("[yellow]No active sessions to attach.[/yellow]")
+            raise typer.Exit(1)
+        session_id = active_sessions[-1].session_id
+
     session = client.get_session(session_id)
     if not session:
         err_console.print(f"[red]Error:[/red] Session {session_id} not found.")
@@ -170,7 +181,11 @@ def ls_shortcut():
 
 
 @app.command("attach")
-def attach_shortcut(session_id: str):
+def attach_shortcut(
+    session_id: str | None = typer.Argument(
+        None, help="Target session ID (defaults to latest active session)"
+    ),
+):
     """Shortcut for `session attach`."""
     session_attach(session_id)
 
@@ -266,6 +281,98 @@ def logs_command(
         raise typer.Exit(1) from None
 
 
+@app.command("cp")
+def cp_command(
+    src: str = typer.Argument(..., help="Source path (e.g. ./file or s_12345:/remote/path)"),
+    dest: str = typer.Argument(..., help="Destination path (e.g. s_12345:/remote/path or ./file)"),
+):
+    """Copy files or directories between local machine and remote session (like docker cp)."""
+    ensure_daemon_running()
+    client = Client()
+
+    is_download = ":" in src and not src.startswith("http://") and not src.startswith("https://")
+    is_upload = ":" in dest and not dest.startswith("http://") and not dest.startswith("https://")
+
+    if is_download and is_upload:
+        err_console.print(
+            "[red]Error:[/red] Direct session-to-session copy is not supported. Use a local staging path."
+        )
+        raise typer.Exit(1) from None
+
+    if not is_download and not is_upload:
+        err_console.print(
+            "[red]Error:[/red] One of SRC or DEST must include SESSION_ID (e.g. `remote-cli cp ./app.tar.gz s_12345:/opt/`)"
+        )
+        raise typer.Exit(1) from None
+
+    try:
+        if is_download:
+            session_id, remote_path = src.split(":", 1)
+            with console.status(
+                f"[cyan]Downloading [bold]{remote_path}[/bold] from session {session_id}...[/cyan]"
+            ):
+                client.download_file(session_id, remote_path, dest)
+            console.print(
+                f"[green]✓ Successfully downloaded [bold]{remote_path}[/bold] -> [bold]{dest}[/bold][/green]"
+            )
+        else:
+            session_id, remote_path = dest.split(":", 1)
+            with console.status(
+                f"[cyan]Uploading [bold]{src}[/bold] to session {session_id}:{remote_path}...[/cyan]"
+            ):
+                client.upload_file(session_id, src, remote_path)
+            console.print(
+                f"[green]✓ Successfully uploaded [bold]{src}[/bold] -> [bold]{session_id}:{remote_path}[/bold][/green]"
+            )
+    except Exception as e:
+        err_console.print(f"[red]Copy error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command("upload")
+def upload_command(
+    session_id: str = typer.Argument(..., help="Target session ID"),
+    local_path: str = typer.Argument(..., help="Local file or directory path"),
+    remote_path: str = typer.Argument(..., help="Remote destination path on server"),
+):
+    """Upload a local file or directory to remote session."""
+    ensure_daemon_running()
+    client = Client()
+    try:
+        with console.status(
+            f"[cyan]Uploading [bold]{local_path}[/bold] to {session_id}:{remote_path}...[/cyan]"
+        ):
+            client.upload_file(session_id, local_path, remote_path)
+        console.print(
+            f"[green]✓ Successfully uploaded [bold]{local_path}[/bold] -> [bold]{session_id}:{remote_path}[/bold][/green]"
+        )
+    except Exception as e:
+        err_console.print(f"[red]Upload error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command("download")
+def download_command(
+    session_id: str = typer.Argument(..., help="Target session ID"),
+    remote_path: str = typer.Argument(..., help="Remote file or directory path on server"),
+    local_path: str = typer.Argument(..., help="Local destination path"),
+):
+    """Download a remote file or directory from session to local machine."""
+    ensure_daemon_running()
+    client = Client()
+    try:
+        with console.status(
+            f"[cyan]Downloading [bold]{remote_path}[/bold] from {session_id} to {local_path}...[/cyan]"
+        ):
+            client.download_file(session_id, remote_path, local_path)
+        console.print(
+            f"[green]✓ Successfully downloaded [bold]{remote_path}[/bold] -> [bold]{local_path}[/bold][/green]"
+        )
+    except Exception as e:
+        err_console.print(f"[red]Download error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
 @daemon_app.command("start")
 def daemon_start():
     """Start the daemon process explicitly in foreground or background."""

{remote_cli-0.1.0 → remote_cli-0.2.0}/src/remote_cli/client.py

@@ -162,3 +162,39 @@ class Client:
         )
         resp = self._send_request(req)
         return resp.success
+
+    def upload_file(
+        self,
+        session_id: str,
+        local_path: str | Path,
+        remote_path: str,
+        progress_callback=None,
+    ) -> None:
+        """Uploads a local file or directory to remote_path in the session."""
+        from .transfer import TransferManager
+
+        tm = TransferManager(self)
+        tm.upload(
+            session_id=session_id,
+            local_path=local_path,
+            remote_path=remote_path,
+            progress_callback=progress_callback,
+        )
+
+    def download_file(
+        self,
+        session_id: str,
+        remote_path: str,
+        local_path: str | Path,
+        progress_callback=None,
+    ) -> None:
+        """Downloads a remote file or directory from the session to local_path."""
+        from .transfer import TransferManager
+
+        tm = TransferManager(self)
+        tm.download(
+            session_id=session_id,
+            remote_path=remote_path,
+            local_path=local_path,
+            progress_callback=progress_callback,
+        )

{remote_cli-0.1.0 → remote_cli-0.2.0}/src/remote_cli/daemon.py

@@ -281,12 +281,42 @@ def ensure_daemon_running() -> None:
 def stop_daemon() -> bool:
     """Stops the running daemon process."""
     pid_path = get_pid_path()
+    sock_path = get_socket_path()
     if not pid_path.exists():
+        if sock_path.exists():
+            try:
+                sock_path.unlink()
+            except Exception:
+                pass
         return False
     try:
         pid = int(pid_path.read_text().strip())
-        os.kill(pid, signal.SIGTERM)
-        time.sleep(0.3)
+        try:
+            os.kill(pid, signal.SIGTERM)
+            for _ in range(20):
+                time.sleep(0.1)
+                try:
+                    os.kill(pid, 0)
+                except OSError:
+                    break
+            else:
+                try:
+                    os.kill(pid, signal.SIGKILL)
+                except OSError:
+                    pass
+        except OSError:
+            pass
+
+        if pid_path.exists():
+            try:
+                pid_path.unlink()
+            except Exception:
+                pass
+        if sock_path.exists():
+            try:
+                sock_path.unlink()
+            except Exception:
+                pass
         return True
     except Exception:
         return False

{remote_cli-0.1.0 → remote_cli-0.2.0}/src/remote_cli/session.py

@@ -149,33 +149,15 @@ class Session:
         if self.master_fd is not None:
             self._set_pty_size(self.master_fd, rows, cols)
 
-    def _on_pty_readable(self) -> None:
-        """Callback invoked when PTY master has output to read."""
-        if self.master_fd is None:
-            return
-
-        try:
-            data = os.read(self.master_fd, 4096)
-        except (BlockingIOError, InterruptedError):
-            return
-        except OSError:
-            # PTY slave closed / child exited
-            data = b""
-
-        if not data:
-            self._on_process_exit()
-            return
-
-        # Feed screen and buffer
+    def _handle_output_data(self, data: bytes) -> None:
+        """Processes output bytes received from PTY."""
         self.screen.feed(data)
         self.buffer.append(data)
 
-        # Feed active watcher
         if self.active_watcher:
             text = data.decode("utf-8", errors="replace")
             self.active_watcher.feed(text)
 
-        # Broadcast to all attached clients
         dead_writers = set()
         for writer in self.attached_writers:
             try:
@@ -186,6 +168,24 @@ class Session:
         for writer in dead_writers:
             self.attached_writers.discard(writer)
 
+    def _on_pty_readable(self) -> None:
+        """Callback invoked when PTY master has output to read."""
+        if self.master_fd is None:
+            return
+
+        try:
+            data = os.read(self.master_fd, 4096)
+        except (BlockingIOError, InterruptedError):
+            return
+        except OSError:
+            data = b""
+
+        if not data:
+            self._on_process_exit()
+            return
+
+        self._handle_output_data(data)
+
     def _on_process_exit(self) -> None:
         """Handles PTY close and subprocess termination."""
         if self.master_fd is not None:
@@ -204,6 +204,16 @@ class Session:
             except Exception:
                 pass
 
+        # Clean up ControlMaster socket if exists
+        try:
+            from .utils import get_cm_socket_path
+
+            cm_sock = get_cm_socket_path(self.session_id)
+            if cm_sock.exists():
+                cm_sock.unlink()
+        except Exception:
+            pass
+
         # Notify attached writers
         for writer in list(self.attached_writers):
             try:
@@ -219,11 +229,43 @@ class Session:
             )
 
     def write_input(self, data: bytes) -> None:
-        """Writes raw input bytes to the PTY."""
+        """Writes raw input bytes to the PTY with non-blocking flow control and echo draining."""
         if self.master_fd is None or self.status != "active":
             raise RuntimeError(f"Session {self.session_id} is not active")
         try:
-            os.write(self.master_fd, data)
+            import select
+            import time
+
+            total_written = 0
+            total_len = len(data)
+
+            while total_written < total_len:
+                if self.master_fd is None or self.status != "active":
+                    break
+
+                # 1. Drain pending output from PTY to prevent slave echo buffer deadlock
+                try:
+                    rlist, _, _ = select.select([self.master_fd], [], [], 0)
+                    if self.master_fd in rlist:
+                        chunk_out = os.read(self.master_fd, 4096)
+                        if chunk_out:
+                            self._handle_output_data(chunk_out)
+                except Exception:
+                    pass
+
+                # 2. Write chunk
+                chunk = data[total_written : total_written + 512]
+                try:
+                    n = os.write(self.master_fd, chunk)
+                    total_written += n
+                    if total_len > 512:
+                        time.sleep(0.0005)
+                except (BlockingIOError, InterruptedError):
+                    # PTY buffer full: wait briefly and drain
+                    try:
+                        select.select([self.master_fd], [self.master_fd], [], 0.02)
+                    except Exception:
+                        pass
         except Exception as e:
             raise RuntimeError(f"Failed to write to session {self.session_id}: {e}") from e
 
@@ -312,10 +354,29 @@ class SessionManager:
     ) -> Session:
         session_id = generate_session_id()
         session_name = name or f"session-{session_id}"
+
+        # If command starts with ssh, automatically configure ControlMaster
+        final_command = list(command)
+        if final_command and final_command[0] == "ssh":
+            from .utils import get_cm_socket_path
+
+            cm_sock = get_cm_socket_path(session_id)
+            has_cm = any("ControlPath" in str(arg) for arg in final_command)
+            if not has_cm:
+                cm_options = [
+                    "-o",
+                    "ControlMaster=auto",
+                    "-o",
+                    f"ControlPath={cm_sock}",
+                    "-o",
+                    "ControlPersist=600s",
+                ]
+                final_command = [final_command[0]] + cm_options + final_command[1:]
+
         session = Session(
             session_id=session_id,
             name=session_name,
-            command=command,
+            command=final_command,
             rows=rows,
             cols=cols,
         )

remote_cli-0.2.0/src/remote_cli/transfer.py

@@ -0,0 +1,298 @@
+"""File transfer engine for uploading and downloading files over remote-cli sessions."""
+
+import base64
+import hashlib
+import io
+import os
+import shlex
+import tarfile
+from collections.abc import Callable
+from pathlib import Path
+
+from .client import Client
+
+
+def calculate_md5(data: bytes) -> str:
+    """Calculates MD5 hex digest for given bytes."""
+    return hashlib.md5(data).hexdigest()
+
+
+def create_tar_gz_bytes(local_path: Path) -> tuple[bytes, bool]:
+    """
+    Creates a tar.gz archive in memory from a local file or directory.
+    Returns (tar_gz_bytes, is_directory).
+    """
+    local_path = local_path.resolve()
+    if not local_path.exists():
+        raise FileNotFoundError(f"Local path does not exist: {local_path}")
+
+    is_dir = local_path.is_dir()
+    bio = io.BytesIO()
+
+    with tarfile.open(fileobj=bio, mode="w:gz") as tar:
+        if is_dir:
+            for root, _, files in os.walk(local_path):
+                for f in files:
+                    full_p = Path(root) / f
+                    rel_p = full_p.relative_to(local_path)
+                    tar.add(str(full_p), arcname=str(rel_p))
+        else:
+            tar.add(str(local_path), arcname=local_path.name)
+
+    return bio.getvalue(), is_dir
+
+
+def extract_tar_gz_bytes(
+    archive_bytes: bytes, dest_path: Path, single_file_name: str | None = None
+) -> None:
+    """Extracts a tar.gz archive to destination path.
+
+    If destination is a file path and archive contains a single file without directory structure, writes directly to dest_path.
+    """
+    dest_path = dest_path.resolve()
+    bio = io.BytesIO(archive_bytes)
+
+    with tarfile.open(fileobj=bio, mode="r:*") as tar:
+        members = tar.getmembers()
+        has_dirs = any(m.isdir() for m in members)
+
+        # Filter regular files (excluding directory entries, PAX headers, and AppleDouble ._ files)
+        regular_members = [
+            m
+            for m in members
+            if not m.isdir()
+            and not m.name.startswith("PaxHeaders")
+            and not Path(m.name).name.startswith("._")
+        ]
+
+        if len(regular_members) == 1 and not has_dirs and not dest_path.is_dir():
+            # True single file target
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            extracted_f = tar.extractfile(regular_members[0])
+            if extracted_f:
+                dest_path.write_bytes(extracted_f.read())
+        else:
+            dest_path.mkdir(parents=True, exist_ok=True)
+            try:
+                tar.extractall(path=str(dest_path), filter="data")
+            except TypeError:
+                tar.extractall(path=str(dest_path))
+
+
+def is_control_master_active(session_id: str) -> bool:
+    """Checks if an SSH ControlMaster socket is active and responsive for the session."""
+    import subprocess
+
+    from .utils import get_cm_socket_path
+
+    sock = get_cm_socket_path(session_id)
+    if not sock.exists():
+        return False
+
+    try:
+        res = subprocess.run(
+            ["ssh", "-O", "check", "-o", f"ControlPath={sock}", "dummy_host"],
+            capture_output=True,
+            text=True,
+            timeout=2.0,
+        )
+        return res.returncode == 0 or "Master running" in (res.stdout + res.stderr)
+    except Exception:
+        return False
+
+
+class TransferManager:
+    """Manages file transfer over active remote-cli sessions using chunked streams or SSH ControlMaster."""
+
+    def __init__(self, client: Client):
+        self.client = client
+
+    def upload(
+        self,
+        session_id: str,
+        local_path: str | Path,
+        remote_path: str,
+        progress_callback: Callable[[int, int], None] | None = None,
+    ) -> None:
+        """Uploads a local file or directory to remote_path in the session."""
+        loc_p = Path(local_path).resolve()
+        if not loc_p.exists():
+            raise FileNotFoundError(f"Local file or directory not found: {loc_p}")
+
+        # Plan B Fast-Path: Use SSH ControlMaster via native SCP if available
+        if is_control_master_active(session_id):
+            try:
+                import subprocess
+
+                from .utils import get_cm_socket_path
+
+                sock = get_cm_socket_path(session_id)
+                scp_cmd = [
+                    "scp",
+                    "-o",
+                    f"ControlPath={sock}",
+                    "-o",
+                    "BatchMode=yes",
+                    "-o",
+                    "StrictHostKeyChecking=no",
+                ]
+                if loc_p.is_dir():
+                    scp_cmd.append("-r")
+                scp_cmd.extend([str(loc_p), f"dummy_host:{remote_path}"])
+
+                res = subprocess.run(scp_cmd, capture_output=True, text=True, timeout=120.0)
+                if res.returncode == 0:
+                    if progress_callback:
+                        progress_callback(100, 100)
+                    return
+            except Exception:
+                pass  # Fallback to Tar + Base64 stream
+
+        # Fallback Engine: In-band Tar + Base64 single-line stream
+        tar_bytes, is_dir = create_tar_gz_bytes(loc_p)
+        b64_data = base64.b64encode(tar_bytes).decode("ascii")
+        total_len = len(b64_data)
+
+        # Dynamic timeout based on archive size (at least 30s)
+        timeout = max(30.0, float(len(tar_bytes)) / (50 * 1024) + 15.0)
+
+        remote_dest_quoted = shlex.quote(remote_path)
+        is_remote_dir = is_dir or remote_path.endswith("/")
+
+        if is_remote_dir:
+            unpack_cmd = (
+                f'mkdir -p {remote_dest_quoted} && tar -xzf "$__RCLI_TAR" -C {remote_dest_quoted}'
+            )
+        else:
+            unpack_cmd = (
+                f'mkdir -p "$(dirname {remote_dest_quoted})" && '
+                f"__RCLI_EXTRACT_DIR=$(mktemp -d /tmp/rcli_ext_XXXXXX) && "
+                f'tar -xzf "$__RCLI_TAR" -C "$__RCLI_EXTRACT_DIR" && '
+                f'mv "$__RCLI_EXTRACT_DIR/{loc_p.name}" {remote_dest_quoted} && '
+                f'rm -rf "$__RCLI_EXTRACT_DIR"'
+            )
+
+        # Step 1: Create remote staging temp file
+        init_cmd = '__RCLI_B64=$(mktemp /tmp/rcli_up_XXXXXX) && echo "$__RCLI_B64"'
+        init_res = self.client.exec_command(session_id, init_cmd, timeout=15.0)
+        if init_res.exit_code != 0 or not init_res.output.strip():
+            raise RuntimeError(f"Failed to initialize remote upload staging: {init_res.output}")
+
+        remote_b64_file = init_res.output.strip().splitlines()[-1]
+
+        # Step 2: Stream single-line chunks of 512 chars (safe across all PTY & SSH connections)
+        chunk_size = 512
+        sent = 0
+        for i in range(0, total_len, chunk_size):
+            chunk = b64_data[i : i + chunk_size]
+            append_cmd = f"printf '%s' '{chunk}' >> {shlex.quote(remote_b64_file)}"
+            chunk_res = self.client.exec_command(session_id, append_cmd, timeout=timeout)
+            if chunk_res.exit_code != 0:
+                self.client.exec_command(
+                    session_id, f"rm -f {shlex.quote(remote_b64_file)}", timeout=5.0
+                )
+                raise RuntimeError(f"Failed uploading chunk: {chunk_res.output}")
+            sent += len(chunk)
+            if progress_callback:
+                progress_callback(sent, total_len)
+
+        # Step 3: Unpack remotely
+        unpack_script = (
+            f"__RCLI_TAR=$(mktemp /tmp/rcli_pkg_XXXXXX); "
+            f'base64 -d < {shlex.quote(remote_b64_file)} > "$__RCLI_TAR" && '
+            f"rm -f {shlex.quote(remote_b64_file)} && "
+            f"{unpack_cmd} && "
+            f'rm -f "$__RCLI_TAR"'
+        )
+        unpack_res = self.client.exec_command(session_id, unpack_script, timeout=timeout)
+        if unpack_res.exit_code != 0:
+            raise RuntimeError(f"Failed to unpack uploaded file remotely: {unpack_res.output}")
+
+    def download(
+        self,
+        session_id: str,
+        remote_path: str,
+        local_path: str | Path,
+        progress_callback: Callable[[int, int], None] | None = None,
+    ) -> None:
+        """Downloads a remote file or directory from the session to local_path."""
+        loc_p = Path(local_path).resolve()
+
+        # Plan B Fast-Path: Use SSH ControlMaster via native SCP if available
+        if is_control_master_active(session_id):
+            try:
+                import subprocess
+
+                from .utils import get_cm_socket_path
+
+                sock = get_cm_socket_path(session_id)
+                loc_p.parent.mkdir(parents=True, exist_ok=True)
+                scp_cmd = [
+                    "scp",
+                    "-r",
+                    "-o",
+                    f"ControlPath={sock}",
+                    "-o",
+                    "BatchMode=yes",
+                    "-o",
+                    "StrictHostKeyChecking=no",
+                    f"dummy_host:{remote_path}",
+                    str(loc_p),
+                ]
+                res = subprocess.run(scp_cmd, capture_output=True, text=True, timeout=120.0)
+                if res.returncode == 0:
+                    if progress_callback:
+                        progress_callback(100, 100)
+                    return
+            except Exception:
+                pass  # Fallback to Tar + Base64 stream
+
+        # Fallback Engine: In-band Tar + Base64 stream
+        remote_quoted = shlex.quote(remote_path)
+
+        # Pack to tar.gz + base64 with clear sentinel markers
+        pack_script = (
+            f"if [ ! -e {remote_quoted} ]; then echo '__RCLI_NOT_FOUND__'; exit 44; fi; "
+            f"__RCLI_T=$(mktemp /tmp/rcli_dl_XXXXXX); "
+            f"if [ -d {remote_quoted} ]; then "
+            f'tar -czf "$__RCLI_T" -C {remote_quoted} .; '
+            f"else "
+            f"__RCLI_P=$(dirname {remote_quoted}); "
+            f"__RCLI_B=$(basename {remote_quoted}); "
+            f'tar -czf "$__RCLI_T" -C "$__RCLI_P" "$__RCLI_B"; '
+            f"fi && "
+            f"printf '__B64_START__\\n' && "
+            f'base64 < "$__RCLI_T" && '
+            f"printf '\\n__B64_END__\\n'; "
+            f'rm -f "$__RCLI_T"'
+        )
+
+        res = self.client.exec_command(session_id, pack_script, timeout=60.0)
+        if res.exit_code == 44 or "__RCLI_NOT_FOUND__" in res.output:
+            raise FileNotFoundError(f"Remote path not found: {remote_path}")
+        if res.exit_code != 0:
+            raise RuntimeError(f"Failed to package remote file: {res.output}")
+
+        # Extract base64 between markers
+        if "__B64_START__" not in res.output:
+            raise RuntimeError(f"Invalid remote download response: {res.output}")
+
+        _, _, after = res.output.partition("__B64_START__")
+        b64_content, _, _ = after.partition("__B64_END__")
+        import re
+
+        b64_clean = re.sub(r"[^A-Za-z0-9+/=]", "", b64_content)
+        if not b64_clean:
+            raise RuntimeError("Received empty payload from remote server")
+
+        try:
+            tar_bytes = base64.b64decode(b64_clean)
+        except Exception as e:
+            raise RuntimeError(f"Failed to decode base64 download payload: {e}") from e
+
+        if progress_callback:
+            progress_callback(len(tar_bytes), len(tar_bytes))
+
+        # Extract locally
+        single_name = Path(remote_path).name
+        extract_tar_gz_bytes(tar_bytes, loc_p, single_file_name=single_name)

{remote_cli-0.1.0 → remote_cli-0.2.0}/src/remote_cli/utils.py

@@ -30,6 +30,18 @@ def get_log_path() -> Path:
     return get_base_dir() / "daemon.log"
 
 
+def get_cm_dir() -> Path:
+    """Returns the ControlMaster sockets directory."""
+    cm_dir = get_base_dir() / "cm"
+    cm_dir.mkdir(parents=True, exist_ok=True)
+    return cm_dir
+
+
+def get_cm_socket_path(session_id: str) -> Path:
+    """Returns the ControlMaster socket path for a given session."""
+    return get_cm_dir() / f"{session_id}.sock"
+
+
 def generate_session_id() -> str:
     """Generates a short, user-friendly session ID."""
     return f"s_{uuid.uuid4().hex[:8]}"

{remote_cli-0.1.0 → remote_cli-0.2.0}/tests/test_cli.py

@@ -12,6 +12,9 @@ def test_cli_help():
     assert "ssh" in result.output
     assert "exec" in result.output
     assert "snapshot" in result.output
+    assert "cp" in result.output
+    assert "upload" in result.output
+    assert "download" in result.output
 
 
 def test_cli_session_help():
@@ -20,3 +23,10 @@ def test_cli_session_help():
     assert "create" in result.output
     assert "list" in result.output
     assert "attach" in result.output
+
+
+def test_cli_cp_help():
+    result = runner.invoke(app, ["cp", "--help"])
+    assert result.exit_code == 0
+    assert "src" in result.output.lower()
+    assert "dest" in result.output.lower()

remote_cli-0.2.0/tests/test_transfer.py

@@ -0,0 +1,246 @@
+import asyncio
+import os
+import time
+import uuid
+from pathlib import Path
+
+import pytest
+
+from remote_cli.client import Client
+from remote_cli.daemon import DaemonServer
+from remote_cli.transfer import (
+    create_tar_gz_bytes,
+    extract_tar_gz_bytes,
+)
+
+
+@pytest.fixture
+def transfer_server():
+    sock_path = Path(f"/tmp/rcli_tf_{uuid.uuid4().hex[:8]}.sock")
+    server = DaemonServer(socket_path=sock_path)
+    server_loop = asyncio.new_event_loop()
+
+    import threading
+
+    def run_server():
+        asyncio.set_event_loop(server_loop)
+        try:
+            server_loop.run_until_complete(server.start())
+        except Exception:
+            pass
+
+    thread = threading.Thread(target=run_server, daemon=True)
+    thread.start()
+
+    for _ in range(50):
+        if sock_path.exists():
+            break
+        time.sleep(0.05)
+
+    client = Client(socket_path=sock_path)
+    assert client.ping() is True
+
+    yield client, server
+
+    for s in list(server.session_manager.sessions.values()):
+        s.close()
+
+    def stop_server():
+        if server.server:
+            server.server.close()
+        server_loop.stop()
+
+    server_loop.call_soon_threadsafe(stop_server)
+    thread.join(timeout=1.0)
+    if sock_path.exists():
+        try:
+            sock_path.unlink()
+        except Exception:
+            pass
+
+
+def test_tar_gz_bytes_roundtrip(tmp_path: Path):
+    # Test directory archive & extract
+    src_dir = tmp_path / "src_dir"
+    src_dir.mkdir()
+    (src_dir / "file1.txt").write_text("Hello file 1")
+    sub = src_dir / "sub"
+    sub.mkdir()
+    (sub / "file2.bin").write_bytes(b"\x00\x01\x02\x03\x04\xff")
+
+    tar_bytes, is_dir = create_tar_gz_bytes(src_dir)
+    assert is_dir is True
+    assert len(tar_bytes) > 0
+
+    dest_dir = tmp_path / "dest_dir"
+    extract_tar_gz_bytes(tar_bytes, dest_dir)
+    assert (dest_dir / "file1.txt").read_text() == "Hello file 1"
+    assert (dest_dir / "sub" / "file2.bin").read_bytes() == b"\x00\x01\x02\x03\x04\xff"
+
+
+def test_session_upload_and_download(transfer_server, tmp_path: Path):
+    client, _ = transfer_server
+
+    # Create local shell session
+    session_info = client.create_session(command=["/bin/sh"], name="transfer-test")
+    session_id = session_info.session_id
+    time.sleep(0.2)
+
+    # 1. Upload a single file
+    local_file = tmp_path / "upload_test.txt"
+    local_file.write_text("Unique Upload Content 12345\nSecond line")
+
+    remote_dest_file = f"/tmp/rcli_dest_{uuid.uuid4().hex[:6]}.txt"
+    client.upload_file(session_id, local_file, remote_dest_file)
+
+    # Verify content remotely
+    cat_res = client.exec_command(session_id, f"cat {remote_dest_file}", timeout=5.0)
+    assert cat_res.exit_code == 0
+    assert "Unique Upload Content 12345" in cat_res.output
+
+    # 2. Download the file back to a new local path
+    local_download_dest = tmp_path / "downloaded_test.txt"
+    client.download_file(session_id, remote_dest_file, local_download_dest)
+    assert local_download_dest.exists()
+    assert (
+        local_download_dest.read_text().strip()
+        == "Unique Upload Content 12345\nSecond line".strip()
+    )
+
+    # 3. Upload a full directory
+    local_pkg = tmp_path / "my_pkg"
+    local_pkg.mkdir()
+    (local_pkg / "config.yaml").write_text("version: 1.0\napp: test")
+    (local_pkg / "data.bin").write_bytes(os.urandom(1024 * 10))  # 10KB binary
+
+    remote_pkg_dir = f"/tmp/rcli_pkg_{uuid.uuid4().hex[:6]}"
+    client.upload_file(session_id, local_pkg, remote_pkg_dir)
+
+    # Verify directory contents remotely
+    ls_res = client.exec_command(session_id, f"ls {remote_pkg_dir}", timeout=5.0)
+    assert ls_res.exit_code == 0
+    assert "config.yaml" in ls_res.output
+    assert "data.bin" in ls_res.output
+
+    # 4. Download directory back locally
+    local_pkg_download = tmp_path / "downloaded_pkg"
+    client.download_file(session_id, remote_pkg_dir, local_pkg_download)
+    assert (local_pkg_download / "config.yaml").read_text() == "version: 1.0\napp: test"
+    assert (local_pkg_download / "data.bin").read_bytes() == (local_pkg / "data.bin").read_bytes()
+
+    # Cleanup remote files
+    client.exec_command(session_id, f"rm -rf {remote_dest_file} {remote_pkg_dir}", timeout=5.0)
+    client.close_session(session_id)
+
+
+def test_cli_transfer_commands(transfer_server, tmp_path: Path, monkeypatch):
+    client, server = transfer_server
+    monkeypatch.setattr("remote_cli.utils.get_socket_path", lambda: server.socket_path)
+    monkeypatch.setattr("remote_cli.cli.ensure_daemon_running", lambda: None)
+    monkeypatch.setattr("remote_cli.client.get_socket_path", lambda: server.socket_path)
+    from typer.testing import CliRunner
+
+    from remote_cli.cli import app
+
+    runner = CliRunner()
+
+    # Create session
+    session_info = client.create_session(command=["/bin/sh"], name="cli-transfer")
+    sid = session_info.session_id
+    time.sleep(0.2)
+
+    # Test upload command
+    local_f = tmp_path / "cli_up.txt"
+    local_f.write_text("CLI Upload Data")
+    remote_f = f"/tmp/rcli_cli_up_{uuid.uuid4().hex[:6]}.txt"
+
+    res_up = runner.invoke(app, ["upload", sid, str(local_f), remote_f])
+    assert res_up.exit_code == 0
+    assert "Successfully uploaded" in res_up.output
+
+    # Test download command
+    local_dl = tmp_path / "cli_dl.txt"
+    res_dl = runner.invoke(app, ["download", sid, remote_f, str(local_dl)])
+    assert res_dl.exit_code == 0
+    assert "Successfully downloaded" in res_dl.output
+    assert local_dl.read_text().strip() == "CLI Upload Data"
+
+    # Test cp command (upload syntax)
+    local_cp_src = tmp_path / "cli_cp_src.txt"
+    local_cp_src.write_text("CP Command Data")
+    remote_cp_dest = f"/tmp/rcli_cp_{uuid.uuid4().hex[:6]}.txt"
+
+    res_cp_up = runner.invoke(app, ["cp", str(local_cp_src), f"{sid}:{remote_cp_dest}"])
+    assert res_cp_up.exit_code == 0
+    assert "Successfully uploaded" in res_cp_up.output
+
+    # Test cp command (download syntax)
+    local_cp_dl = tmp_path / "cli_cp_dl.txt"
+    res_cp_dl = runner.invoke(app, ["cp", f"{sid}:{remote_cp_dest}", str(local_cp_dl)])
+    assert res_cp_dl.exit_code == 0
+    assert "Successfully downloaded" in res_cp_dl.output
+    assert local_cp_dl.read_text().strip() == "CP Command Data"
+
+    # Cleanup
+    client.exec_command(session_id=sid, command=f"rm -f {remote_f} {remote_cp_dest}")
+    client.close_session(sid)
+
+
+def test_ssh_session_injects_control_master(transfer_server):
+    client, _ = transfer_server
+    # Verify that SessionManager auto-injects ControlMaster for ssh commands
+    session_info = client.create_session(
+        command=["ssh", "-p", "22", "user@example.com"], name="test-ssh-cm"
+    )
+    cmd_str = " ".join(session_info.command)
+    assert "ControlMaster=auto" in cmd_str
+    assert "ControlPath=" in cmd_str
+    assert f"{session_info.session_id}.sock" in cmd_str
+    client.close_session(session_info.session_id)
+
+
+def test_control_master_fast_path(tmp_path: Path, monkeypatch):
+    import remote_cli.transfer as rt
+
+    # Create dummy socket
+    sock_path = tmp_path / "dummy_cm.sock"
+    sock_path.touch()
+
+    # Monkeypatch get_cm_socket_path and is_control_master_active
+    monkeypatch.setattr("remote_cli.utils.get_cm_socket_path", lambda sid: sock_path)
+    monkeypatch.setattr(rt, "is_control_master_active", lambda sid: True)
+
+    assert rt.is_control_master_active("s_test") is True
+
+    # Test TransferManager upload using mock subprocess
+    executed_cmds = []
+
+    def mock_run(cmd, *args, **kwargs):
+        executed_cmds.append(cmd)
+        import subprocess
+
+        return subprocess.CompletedProcess(cmd, returncode=0, stdout="", stderr="")
+
+    monkeypatch.setattr("subprocess.run", mock_run)
+
+    dummy_client = None
+    tm = rt.TransferManager(dummy_client)
+
+    local_f = tmp_path / "test.txt"
+    local_f.write_text("Fast path content")
+    tm.upload("s_test", local_f, "/remote/test.txt")
+
+    assert len(executed_cmds) == 1
+    assert executed_cmds[0][0] == "scp"
+    assert f"ControlPath={sock_path}" in " ".join(executed_cmds[0])
+    assert "dummy_host:/remote/test.txt" in " ".join(executed_cmds[0])
+
+    # Test download fast path
+    executed_cmds.clear()
+    local_dl = tmp_path / "dl.txt"
+    tm.download("s_test", "/remote/test.txt", local_dl)
+
+    assert len(executed_cmds) == 1
+    assert executed_cmds[0][0] == "scp"
+    assert f"ControlPath={sock_path}" in " ".join(executed_cmds[0])
+    assert "dummy_host:/remote/test.txt" in " ".join(executed_cmds[0])