ai-remote 0.4.3 → 0.4.5

package/README.md

@@ -7,53 +7,92 @@
 
 ## 🚀 Quick Start (CLI)
 
-Run immediately with `npx` (zero install):
+Run immediately with `npx` (zero install). `open` names the machine once and
+leaves a session running; every command after it drives that session, so none of
+them repeats the host, the account or the password:
 
 ```bash
 # Connect and open a live supervision window:
 AI_REMOTE_PASSWORD=secret npx ai-remote open 192.168.1.50 -u Administrator
 
 # Take a screenshot:
-AI_REMOTE_PASSWORD=secret npx ai-remote shot 192.168.1.50 -u Administrator -o screen.png
+npx ai-remote shot -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
+npx ai-remote click 500,300
+npx ai-remote type "notepad"
+npx ai-remote key Enter
 
 # Run commands in the remote terminal over SSH:
-npx ai-remote exec 192.168.1.50 "dir"
+npx ai-remote exec "dir"
+
+# Let it go when you are done -- nothing closes on its own:
+npx ai-remote close
 ```
 
 ### 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?
+  ai-remote open <host[:port]>       connect, show a window, and stay open
+
+  ai-remote shot                     screenshot the desktop
+  ai-remote click X,Y                click, --button right|middle, --double
+  ai-remote type  "text"             type into whatever has focus
+  ai-remote key   <Code>             press keys, e.g. MetaLeft, ControlLeft+KeyA
+  ai-remote exec  "cmd"              run a command in the terminal (SSH)
+  ai-remote shell                    an interactive terminal
+  ai-remote do    "steps"            several actions in one go
+  ai-remote view                     open the window on the session
+  ai-remote view --close             close the window, session keeps running
+  ai-remote status                   what the session is doing
+  ai-remote list                     every session that is open
+  ai-remote close                    close it; --all closes every session
+  ai-remote probe [<host[:port]>]    is anything listening?
+```
+
+### Sessions
+
+The session opened last is the one the commands drive, and it lives until it is
+closed -- including across terminals, so an agent and the person watching it
+reach the same desktop. With more than one open, `--session NAME` picks between
+them; a session answers to its name, its host, or `host:port`.
+
+```bash
+npx ai-remote open 192.168.1.50 -u Administrator --session desk
+npx ai-remote open 192.168.1.60 -u Administrator --session build
+
+npx ai-remote list                  # * marks the one commands will use
+npx ai-remote shot --session desk
+npx ai-remote close --all
 ```
 
-### Common Options
+`probe` is the one command besides `open` that still takes an address, because
+it answers whether a session could be opened at all; with no address it probes
+the current session's host.
+
+### Options for `open`
 
 - `-u, --user NAME`: Account name on the host.
 - `-d, --domain NAME`: Windows domain or computer name.
+- `--session NAME`: Name this session (default: `host_port`).
 - `--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`).
+- `--idle MINUTES`: Close an unused session (default: 0, never).
 - `--headless` / `--no-view`: Run headless without opening the viewer window.
+- `--no-reuse`: A second session beside one that is already open.
+
+### Options for the rest
+
+- `--session NAME`: Which session to drive (default: the one opened last).
+- `-o, --out FILE`: Screenshot output file path (default: `screen.png`).
+- `--max-edge N`: Shrink a screenshot to fit N.
 - `--json`: Output machine-readable JSON results on stdout.
 
+The password comes from `AI_REMOTE_PASSWORD` (or `REMOTECTL_PASSWORD`). There is
+no `--password` flag: a command line is visible to every process on the machine.
+
 ---
 
 ## 📦 Library Installation