ai-remote 0.1.0 → 0.3.1

package/README.md

@@ -1,32 +1,62 @@
 # ai-remote
 
-> Pure TypeScript protocol engines (RDP, VNC, SSH) and remote desktop vocabulary for AI agents, Node.js, and web browsers.
+> Pure TypeScript protocol engines (RDP, VNC, SSH) for Node.js, Cloudflare Workers, and web browsers — plus `npx ai-remote`, a CLI that drives a remote desktop and shows you what it is doing.
 
 [![npm version](https://img.shields.io/npm/v/ai-remote.svg)](https://www.npmjs.com/package/ai-remote)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Overview
+## 🚀 Quick Start (CLI)
 
-`ai-remote` is an environment-neutral core protocol library providing client-side implementations for **RDP**, **VNC**, and **SSH**. It powers browser-based remote gateways, terminal sessions, and automated AI agents driving remote desktops.
+Run immediately with `npx` (zero install):
 
-## Features
+```bash
+# Connect and open a live supervision window:
+AI_REMOTE_PASSWORD=secret npx ai-remote open 192.168.1.50 -u Administrator
 
-- **RDP Engine:**
-  - Complete X.224, MCS, and GCC capability negotiation.
-  - CredSSP v6 with NTLMv2 and TLS 1.2 client implementation over WebCrypto.
-  - Fast-path 16-bit interleaved RLE bitmap decoding.
-  - Shared clipboard support (`cliprdr` virtual channel).
-  - RemoteApp (RAIL) window orders and execution.
-- **SSH Engine:**
-  - RFC 4253 binary packet protocol with `curve25519-sha256` / `ecdh-sha2-nistp256`.
-  - AEAD ciphers (`aes256-gcm@openssh.com`, `aes128-gcm@openssh.com`).
-  - Terminal interactive and agent command execution.
-- **VNC Engine:**
-  - RFB protocol integration with Apple Diffie-Hellman handshake support.
-- **AI Agent Tool Vocabulary:**
-  - Standardized connection, device, protocol, and signal definitions.
+# Take a screenshot:
+AI_REMOTE_PASSWORD=secret npx ai-remote shot 192.168.1.50 -u Administrator -o screen.png
+
+# Click or type on the remote desktop:
+npx ai-remote click 192.168.1.50 500,300
+npx ai-remote type 192.168.1.50 "notepad"
+npx ai-remote key 192.168.1.50 Enter
+
+# Run commands in the remote terminal over SSH:
+npx ai-remote exec 192.168.1.50 "dir"
+```
+
+### CLI Commands
+
+```
+  ai-remote open   <host[:port]>          connect, show a window, and stay open
+  ai-remote shot   <host[:port]>          screenshot the desktop
+  ai-remote click  <host[:port]> X,Y      click, --button right|middle, --double
+  ai-remote type   <host[:port]> "text"   type into whatever has focus
+  ai-remote key    <host[:port]> <Code>   press keys, e.g. MetaLeft, ControlLeft+KeyA
+  ai-remote exec   <host[:port]> "cmd"    run a command in the terminal (SSH)
+  ai-remote shell  <host[:port]>          an interactive terminal
+  ai-remote do     <host[:port]> "steps"  several actions in one go
+  ai-remote view   <host[:port]>          open the window on a running session
+  ai-remote view   <host[:port]> --close  close the window, session keeps running
+  ai-remote status | list | close [<host>]
+  ai-remote probe  <host[:port]>          is anything listening?
+```
+
+### Common Options
+
+- `-u, --user NAME`: Account name on the host.
+- `-d, --domain NAME`: Windows domain or computer name.
+- `--ssh-user NAME`: Account for the SSH terminal (defaults to `--user`).
+- `--ssh-port N`: SSH port (default: 22).
+- `-s, --security MODE`: `auto` | `nla` | `tls` | `rdp` (default: `auto`).
+- `-W, --width N` / `-H, --height N`: Desktop resolution (default: 1280x800).
+- `-o, --out FILE`: Screenshot output file path (default: `screen.png`).
+- `--headless` / `--no-view`: Run headless without opening the viewer window.
+- `--json`: Output machine-readable JSON results on stdout.
+
+---
 
-## Installation
+## 📦 Library Installation
 
 ```bash
 pnpm add ai-remote
@@ -34,7 +64,7 @@ pnpm add ai-remote
 npm install ai-remote
 ```
 
-## Subpath Exports
+### Subpath Exports
 
 | Export | Description |
 |---|---|
@@ -45,6 +75,25 @@ npm install ai-remote
 | `ai-remote/protocols/vnc` | VNC session and input management |
 | `ai-remote/shared/*` | Direct access to shared models and utilities |
 
+---
+
+## ✨ Features
+
+- **RDP Protocol Engine:**
+  - Full X.224, MCS, and GCC capability negotiation.
+  - CredSSP v6 with NTLMv2 and TLS 1.2 client implementation over WebCrypto.
+  - Fast-path 16-bit interleaved RLE bitmap decoding.
+  - Shared clipboard support (`cliprdr` virtual channel).
+  - RemoteApp (RAIL) window orders and execution.
+- **SSH Engine:**
+  - RFC 4253 binary packet protocol with `curve25519-sha256` / `ecdh-sha2-nistp256`.
+  - AEAD ciphers (`aes256-gcm@openssh.com`, `aes128-gcm@openssh.com`).
+  - Terminal interactive and automated agent command execution.
+- **VNC Engine:**
+  - RFB protocol integration with Apple Diffie-Hellman handshake support.
+- **AI Agent Automation:**
+  - Fast headless actions, structured screen capture, and auto-attached SSH shells.
+
 ## License
 
 MIT © Leon Guo