remote-cli 0.1.0__tar.gz

remote_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies & run tests
+        run: |
+          uv sync
+          uv run pytest -v
+
+  build-and-publish:
+    name: Build and Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/remote-cli
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing
+      contents: write  # For creating GitHub Releases
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Necessary for hatch-vcs to resolve version from tag
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Works with PyPI Trusted Publishing (OIDC) or PYPI_API_TOKEN secret
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: dist/*
+          generate_release_notes: true

remote_cli-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+src/remote_cli/_version.py
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Operating System & Editors
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# remote-cli local runtime files
+.remote-cli/
+*.sock
+*.pid
+*.log

remote_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

remote_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8DE4732A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

remote_cli-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: remote-cli
+Version: 0.1.0
+Summary: A shared SSH CLI tool for AI Agent and human co-piloting
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyte>=0.8.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# remote-cli
+
+> **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`.
+
+---
+
+## Key Features
+
+- 🤝 **Real-Time Human & Agent Co-piloting**:
+  - The human sees everything the Agent does in their original terminal window in real-time.
+  - The human can continue typing and operating in the same session at any time.
+- ⚡ **Zero External Binary Dependencies**:
+  - Pure Python + POSIX PTY (`pty.openpty`, `termios`, `tty`).
+  - No need to install `tmux` or `screen` on local or remote servers.
+- 🤖 **First-Class AI Agent Support**:
+  - `exec`: Structured execution of shell commands with stdout capture and return codes.
+  - `snapshot`: In-memory 2D virtual terminal rendering (`pyte`) for clean screen capture (even for ncurses / curses / colored prompts).
+  - `send`: Keystrokes and control signals (`Ctrl+C`, `Ctrl+D`, confirmation answers `y/n`).
+  - `logs`: Fast access to recent scrollback history.
+- 🔌 **Seamless Background Daemon**:
+  - Communicates via Unix Domain Sockets (`~/.remote-cli/remote-cli.sock`).
+  - Transparently auto-starts in the background on demand.
+  - Safely detach (`Ctrl+]`) and re-attach (`remote-cli attach <session-id>`) anytime.
+
+---
+
+## Installation & Setup
+
+Using [`uv`](https://github.com/astral-sh/uv):
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/remote-cli.git
+cd remote-cli
+
+# Install dependencies and create venv
+uv sync
+
+# Run directly via uv
+uv run remote-cli --help
+```
+
+---
+
+## Quickstart & Workflow
+
+### 1. Human Starts SSH Session
+The user initiates the SSH connection to the remote machine. Once connected and authenticated, a `Session ID` is displayed:
+
+```bash
+uv run remote-cli ssh user@server.example.com
+```
+
+Output:
+```text
+╭────────────────────── remote-cli SSH Session ──────────────────────╮
+│ Session Created: s_7f8a9b2c                                        │
+│ Agent Command: remote-cli exec s_7f8a9b2c "<command>"               │
+│ Press Ctrl+] to detach from session at any time.                  │
+╰────────────────────────────────────────────────────────────────────╯
+user@server.example.com's password: ***
+user@server:~$ _
+```
+
+> **Tip**: You can also create local shell sessions for testing:
+> ```bash
+> uv run remote-cli session create --name my-session -- /bin/bash
+> ```
+
+---
+
+### 2. Share `session-id` with AI Agent
+
+Simply tell your AI Agent:
+> *"I have logged into the server. The session ID is `s_7f8a9b2c`. Please check the disk space and restart Nginx."*
+
+The Agent can now execute commands on the remote server via `remote-cli`:
+
+```bash
+# Agent runs a command and captures return code and stdout
+uv run remote-cli exec s_7f8a9b2c "df -h"
+
+# Agent runs a command with JSON output
+uv run remote-cli exec s_7f8a9b2c "systemctl status nginx" --json
+
+# Agent inspects the current 2D screen state
+uv run remote-cli snapshot s_7f8a9b2c
+
+# Agent sends an interactive response (e.g. confirming a prompt)
+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
+```
+
+---
+
+### 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.
+
+---
+
+## CLI Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `remote-cli ssh [SSH_ARGS...]` | Start SSH session, print Session ID, and attach immediately |
+| `remote-cli session create [-d] [-- <CMD...>]` | Create a new session (default: `/bin/bash`) |
+| `remote-cli session list` (or `ls`) | List all active and recent sessions |
+| `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 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
+
+```text
+┌─────────────────────────┐          ┌───────────────────────────┐
+│   Human User Terminal   │          │     AI Agent / Script     │
+│       (Raw Mode)        │          │ (remote-cli exec/snapshot)│
+└────────────┬────────────┘          └─────────────┬─────────────┘
+             │                                     │
+             │   Attach (Stdin/Stdout stream)      │ JSON Request/Response
+             ▼                                     ▼
+   ┌─────────────────────────────────────────────────────────────┐
+   │             remote-cli Daemon Process                       │
+   │       (Unix Domain Socket: ~/.remote-cli/remote-cli.sock)   │
+   │                                                             │
+   │  ┌────────────────────────────────────────────────────────┐ │
+   │  │ Session (e.g. s_7f8a9b2c)                              │ │
+   │  │  - Master/Slave PTY (`pty.openpty`)                    │ │
+   │  │  - Pyte Virtual Terminal Screen (`pyte.HistoryScreen`) │ │
+   │  │  - Scrollback Ring Buffer                              │ │
+   │  │  - Exec Sentinel Detection Engine                      │ │
+   │  │  - Process: `ssh user@remote-server` (or local shell)  │ │
+   │  └────────────────────────────────────────────────────────┘ │
+   └─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Running Tests
+
+```bash
+uv run pytest -v
+```

remote_cli-0.1.0/README.md

@@ -0,0 +1,154 @@
+# remote-cli
+
+> **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`.
+
+---
+
+## Key Features
+
+- 🤝 **Real-Time Human & Agent Co-piloting**:
+  - The human sees everything the Agent does in their original terminal window in real-time.
+  - The human can continue typing and operating in the same session at any time.
+- ⚡ **Zero External Binary Dependencies**:
+  - Pure Python + POSIX PTY (`pty.openpty`, `termios`, `tty`).
+  - No need to install `tmux` or `screen` on local or remote servers.
+- 🤖 **First-Class AI Agent Support**:
+  - `exec`: Structured execution of shell commands with stdout capture and return codes.
+  - `snapshot`: In-memory 2D virtual terminal rendering (`pyte`) for clean screen capture (even for ncurses / curses / colored prompts).
+  - `send`: Keystrokes and control signals (`Ctrl+C`, `Ctrl+D`, confirmation answers `y/n`).
+  - `logs`: Fast access to recent scrollback history.
+- 🔌 **Seamless Background Daemon**:
+  - Communicates via Unix Domain Sockets (`~/.remote-cli/remote-cli.sock`).
+  - Transparently auto-starts in the background on demand.
+  - Safely detach (`Ctrl+]`) and re-attach (`remote-cli attach <session-id>`) anytime.
+
+---
+
+## Installation & Setup
+
+Using [`uv`](https://github.com/astral-sh/uv):
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/remote-cli.git
+cd remote-cli
+
+# Install dependencies and create venv
+uv sync
+
+# Run directly via uv
+uv run remote-cli --help
+```
+
+---
+
+## Quickstart & Workflow
+
+### 1. Human Starts SSH Session
+The user initiates the SSH connection to the remote machine. Once connected and authenticated, a `Session ID` is displayed:
+
+```bash
+uv run remote-cli ssh user@server.example.com
+```
+
+Output:
+```text
+╭────────────────────── remote-cli SSH Session ──────────────────────╮
+│ Session Created: s_7f8a9b2c                                        │
+│ Agent Command: remote-cli exec s_7f8a9b2c "<command>"               │
+│ Press Ctrl+] to detach from session at any time.                  │
+╰────────────────────────────────────────────────────────────────────╯
+user@server.example.com's password: ***
+user@server:~$ _
+```
+
+> **Tip**: You can also create local shell sessions for testing:
+> ```bash
+> uv run remote-cli session create --name my-session -- /bin/bash
+> ```
+
+---
+
+### 2. Share `session-id` with AI Agent
+
+Simply tell your AI Agent:
+> *"I have logged into the server. The session ID is `s_7f8a9b2c`. Please check the disk space and restart Nginx."*
+
+The Agent can now execute commands on the remote server via `remote-cli`:
+
+```bash
+# Agent runs a command and captures return code and stdout
+uv run remote-cli exec s_7f8a9b2c "df -h"
+
+# Agent runs a command with JSON output
+uv run remote-cli exec s_7f8a9b2c "systemctl status nginx" --json
+
+# Agent inspects the current 2D screen state
+uv run remote-cli snapshot s_7f8a9b2c
+
+# Agent sends an interactive response (e.g. confirming a prompt)
+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
+```
+
+---
+
+### 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.
+
+---
+
+## CLI Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `remote-cli ssh [SSH_ARGS...]` | Start SSH session, print Session ID, and attach immediately |
+| `remote-cli session create [-d] [-- <CMD...>]` | Create a new session (default: `/bin/bash`) |
+| `remote-cli session list` (or `ls`) | List all active and recent sessions |
+| `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 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
+
+```text
+┌─────────────────────────┐          ┌───────────────────────────┐
+│   Human User Terminal   │          │     AI Agent / Script     │
+│       (Raw Mode)        │          │ (remote-cli exec/snapshot)│
+└────────────┬────────────┘          └─────────────┬─────────────┘
+             │                                     │
+             │   Attach (Stdin/Stdout stream)      │ JSON Request/Response
+             ▼                                     ▼
+   ┌─────────────────────────────────────────────────────────────┐
+   │             remote-cli Daemon Process                       │
+   │       (Unix Domain Socket: ~/.remote-cli/remote-cli.sock)   │
+   │                                                             │
+   │  ┌────────────────────────────────────────────────────────┐ │
+   │  │ Session (e.g. s_7f8a9b2c)                              │ │
+   │  │  - Master/Slave PTY (`pty.openpty`)                    │ │
+   │  │  - Pyte Virtual Terminal Screen (`pyte.HistoryScreen`) │ │
+   │  │  - Scrollback Ring Buffer                              │ │
+   │  │  - Exec Sentinel Detection Engine                      │ │
+   │  │  - Process: `ssh user@remote-server` (or local shell)  │ │
+   │  └────────────────────────────────────────────────────────┘ │
+   └─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Running Tests
+
+```bash
+uv run pytest -v
+```

remote_cli-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "remote-cli"
+dynamic = ["version"]
+description = "A shared SSH CLI tool for AI Agent and human co-piloting"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.10.0",
+    "pyte>=0.8.2",
+    "rich>=13.9.0",
+    "typer>=0.15.0",
+]
+
+[project.scripts]
+remote-cli = "remote_cli.cli:app"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/remote_cli/_version.py"
+
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.16.5",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+ignore = ["E501", "B008"]
+
+

remote_cli-0.1.0/skills/remote-cli/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: remote-cli
+description: >-
+  Operate shared remote SSH and terminal sessions with human co-pilots using remote-cli.
+  Use when the user provides a session ID to perform remote server operations, deployments,
+  debugging, inspecting terminal outputs, or sending inputs to active SSH sessions.
+---
+
+# Remote CLI Agent Skill (`remote-cli`)
+
+`remote-cli` enables an AI Agent to co-pilot an active SSH or terminal session with a human user. The human logs into the server (handling passwords, 2FA, bastion hosts, and SSH keys) and provides a `session-id` to the Agent. The Agent can then execute commands, inspect terminal output, send keystrokes, and read screen state while the human observes the operations in real-time in their terminal window.
+
+---
+
+## 1. Installation
+
+If `remote-cli` is not already installed in the environment:
+
+```bash
+# Recommended installation via uv tool:
+uv tool install remote-cli
+
+# Or via pip:
+pip install remote-cli
+```
+
+*(If running from local source repository during development: `uv run remote-cli ...`)*
+
+---
+
+## 2. Typical Interaction Workflow
+
+```text
+1. User logs into remote server:
+   $ remote-cli ssh user@remote-host
+   -> Outputs Session ID: s_7f8a9b2c
+
+2. User gives Session ID to Agent:
+   "I've logged in. The session ID is s_7f8a9b2c. Please check disk space and Docker containers."
+
+3. Agent runs commands via remote-cli:
+   $ remote-cli exec s_7f8a9b2c "df -h"
+   $ remote-cli exec s_7f8a9b2c "docker ps"
+
+4. Human sees output in real time in their terminal and can intervene anytime.
+```
+
+---
+
+## 3. Command Reference for Agents
+
+### 3.1. Execute Commands (`remote-cli exec`)
+
+Executes a command inside the remote shell, captures stdout, and returns the exit code.
+
+```bash
+# Standard execution (prints output; returns remote exit code)
+remote-cli exec <session-id> "<command>"
+
+# Example:
+remote-cli exec s_7f8a9b2c "systemctl status nginx"
+
+# Structured JSON output (returns JSON object with exit_code, output, duration, timed_out)
+remote-cli exec s_7f8a9b2c "uname -a" --json
+
+# Custom timeout (default: 30s)
+remote-cli exec s_7f8a9b2c "sleep 5 && echo done" --timeout 60
+```
+
+> **JSON Output Format**:
+> ```json
+> {
+>   "session_id": "s_7f8a9b2c",
+>   "command": "uname -a",
+>   "exit_code": 0,
+>   "output": "Linux server 5.15.0-88-generic ...",
+>   "duration": 0.045,
+>   "timed_out": false
+> }
+> ```
+
+---
+
+### 3.2. Inspect 2D Screen Snapshot (`remote-cli snapshot`)
+
+Captures the rendered 2D terminal screen state (ANSI escapes rendered into clean text lines).
+Use this when you need to see what is currently visible on the user's screen (e.g. interactive prompts, curses/ncurses UIs, `top`, menus).
+
+```bash
+remote-cli snapshot <session-id>
+```
+
+---
+
+### 3.3. Send Interactive Input & Control Keys (`remote-cli send`)
+
+Sends raw text, keystrokes, or control characters into the active session. Useful when answering interactive prompts (like `y/n`, sudo password, confirmation dialogues) or interrupting long processes.
+
+```bash
+# Answer confirmation prompt (appends newline by default):
+remote-cli send <session-id> "y"
+
+# Send text without newline:
+remote-cli send <session-id> "some-text" --no-newline
+
+# Send Ctrl+C (SIGINT) to interrupt a process:
+remote-cli send <session-id> --ctrl-c
+
+# Send Ctrl+D (EOF):
+remote-cli send <session-id> --ctrl-d
+```
+
+---
+
+### 3.4. View Recent Scrollback Logs (`remote-cli logs`)
+
+Retrieves the recent stream output buffer.
+
+```bash
+# Get last 100 lines (default)
+remote-cli logs <session-id>
+
+# Get last N lines
+remote-cli logs <session-id> --lines 50
+```
+
+---
+
+### 3.5. List Active Sessions (`remote-cli session list` / `remote-cli ls`)
+
+Discovers active and recent sessions.
+
+```bash
+remote-cli ls
+```
+
+---
+
+## 4. Agent Guidelines & Best Practices
+
+1. **Check Session Status**:
+   - If the user provided a session ID, you can verify it exists with `remote-cli ls` or directly execute a probe command like `remote-cli exec <session-id> "echo ok"`.
+2. **Handle Exit Codes**:
+   - Always check the exit code. If `exit_code != 0`, analyze the error output before proceeding with dependent operations.
+3. **Interactive Prompts**:
+   - If a command blocks or you suspect an interactive prompt (e.g., `Do you want to continue? [Y/n]`), use `remote-cli snapshot <session-id>` to read the screen, and then use `remote-cli send <session-id> "y"` to reply.
+4. **Transparent Communication**:
+   - Inform the user of the operations you are performing. Remember that the user can see your commands and their outputs on their screen in real time!

remote_cli-0.1.0/src/remote_cli/__init__.py

@@ -0,0 +1,15 @@
+"""remote-cli: Shared SSH CLI tool for AI Agent and human co-piloting."""
+
+try:
+    from ._version import __version__, __version_tuple__
+except ImportError:
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("remote-cli")
+        __version_tuple__ = (0, 1, 0)
+    except Exception:
+        __version__ = "0.1.0"
+        __version_tuple__ = (0, 1, 0)
+
+__all__ = ["__version__", "__version_tuple__"]

remote_cli-0.1.0/src/remote_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+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)
+
+__commit_id__ = commit_id = None