@plori/cli 0.2.6 → 0.3.0

package/README.md

@@ -9,30 +9,129 @@ get_run_result → `result`, …).
 
 ## Install
 
-Build from this repository (Go ≥ 1.26):
+```sh
+curl -fsSL https://plori.ai/install.sh | sh
+```
+
+Windows:
+
+```powershell
+irm https://plori.ai/install.ps1 | iex
+```
+
+Both installers drop a single static binary (no sudo, no Node) and verify it
+against the sha512 the npm registry publishes for that build. Re-run either one
+to upgrade. `PLORI_VERSION`, `PLORI_INSTALL_DIR` and `PLORI_REGISTRY` override
+the defaults.
+
+`install.sh` installs to `~/.local/bin` and edits no shell rc file, so if that
+directory is not already on your PATH the script prints the one line to add and
+`plori` runs only once you have added it. `install.ps1` installs to
+`%LOCALAPPDATA%\plori\bin` and does add that to your user PATH, so a new
+terminal finds it. The scripts are `web/public/install.sh` and
+`web/public/install.ps1` in this repository;
+`.github/scripts/install-sh.test.sh` runs the shell one in clean musl and glibc
+containers.
+
+If you would rather go through npm:
 
 ```sh
-go build -o plori ./cli/cmd/plori
+npm i -g @plori/cli
 ```
 
-Binary releases and an npm wrapper (`@plori/cli`) are published per
-`docs/release-channels.md`.
+Or build from this repository (Go ≥ 1.26):
+
+```sh
+go build -o plori ./cli/cmd/plori
+```
 
 ## Authenticate
 
-Create an API key at <https://plori.ai/dashboard/settings>, then either:
+For an interactive terminal, start the sign-in from the CLI. It opens Plori's
+email-OTP page in your browser and returns to the terminal when complete; a new
+email creates the account in the same flow.
 
 ```sh
-plori login                  # prompts for the key, validates it, stores it 0600
-export PLORI_API_KEY=…       # or: environment (CI, agents)
+plori login
+```
+
+The browser flow requests `openid offline_access mcp`. Its public OAuth client
+id, short-lived access token, rotating refresh token, expiry, and scopes are
+stored in `~/.config/plori/config.json` (or
+`$XDG_CONFIG_HOME/plori/config.json`) with mode `0600`; the CLI refreshes the
+session there when needed.
+
+For CI or another headless environment, keep using an API key created at
+<https://plori.ai/dashboard/settings>:
+
+```sh
+plori login --key plori_sk_…
+# or, without writing a file:
+export PLORI_API_KEY=plori_sk_…
 ```
 
 `PLORI_BASE_URL` (or `--base-url`) points the CLI at a non-production
 control-plane, e.g. a local `uat-server`.
 
+## Attach
+
+`plori attach` opens a live session in your terminal: the recent history, a
+prompt, streaming output, and the approval queue in one place. It is the same
+session the web app shows, so a turn you send here appears in an open browser
+tab as it streams.
+
+**The terminal does not give the agent access to your local files.** The shell,
+the disk, and the files are the agent's own cloud computer. Nothing on your
+machine is uploaded, and nothing the agent writes lands in the directory you
+ran the command from.
+
+```sh
+plori attach mate                     # the agent's most recent session
+plori attach mate --session <id>      # a specific session of that agent
+plori attach mate --history 50        # replay 50 turns instead of the default 20
+plori attach mate --read-only         # tail it, no prompt
+plori attach mate --verbose           # also print reasoning and tool results
+```
+
+The argument is an agent name, an agent id, or a session id, so a session id
+copied out of the web app works on its own. With no stored credentials, attach
+runs the browser sign-in inline and continues once it completes. `--history 0`
+replays nothing; `--history all` replays everything one request can carry,
+which stops at the newest 20,000 stored events. `--base-url` (or
+`PLORI_BASE_URL`) points attach at a non-production control-plane, like every
+other command.
+
+While attached:
+
+- A line of text sends a turn. If a turn is already running, the line steers
+  that turn instead of starting a second one, and attach prints whether the
+  server gave it to the model straight away or queued it for the next round.
+- `Ctrl-C` cancels the running turn. Press it again within two seconds to
+  leave.
+- `Ctrl-D` on an empty line, or `/exit` (`/quit`), detaches only. The run keeps
+  going on the server, and attaching again picks it up where it is.
+- The slash commands are `/sessions` (list this agent's sessions), `/new`
+  (start one), `/model <slug>` (change the model), `/web` (print this session's
+  web address), `/exit`, and `/help`. Anything else that starts with `/` comes
+  back as unknown.
+
+Approvals and input requests are answered where they appear: `y` or `n` for an
+approval, `a` to answer yes and grant standing approval when the request
+carries a consent tool, a line for a value, and a no-echo read for a secret,
+which is never printed to the screen and never reaches your shell history.
+
+The prompt needs a terminal on both ends. With `--read-only`, or when either
+stdin or stdout is redirected, attach drops the prompt and tails the session
+instead, so `plori attach mate | tee session.log` writes a plain transcript
+with no prompt, no echoed keys, and no redraw escape codes. A tail cannot
+answer, so a request that arrives during one is printed with the session's web
+address to answer it at, and a secret is refused rather than read where it
+would echo.
+
 ## Use
 
 ```sh
+plori attach mate                        # open the live session (interactive)
 plori create mate                        # get-or-create an agent named "mate"
 plori run mate "clone repo X and run the tests"
 plori run mate "long job" --no-wait      # returns a run id immediately
@@ -54,8 +153,10 @@ plori workflows execution "rss digest" <exec-id>   # poll one run
 
 Agents are addressed by name or UUID. Every command accepts `--json`; when
 stdout is not a TTY the output is JSON automatically, so scripts and agents
-can parse without flags. Errors go to stderr; exit codes: 0 success, 1 API
-failure, 2 usage error.
+can parse without flags. `plori attach` is the one exception: it is a live
+stream rather than a single result, so it always writes plain text, and a
+redirected stream turns it into a read-only tail. Errors go to stderr; exit
+codes: 0 success, 1 API failure, 2 usage error.
 
 ## For agent authors
 
@@ -70,4 +171,10 @@ row without a `consent_tool` the flag grants nothing. Prefer one long-lived
 agent (`create` returns the existing agent for a reused name) over creating
 new ones.
 
+`plori attach` is for a human at a terminal: it takes over the keyboard and
+expects someone to answer approvals. A calling agent should stay on
+`run`/`result`/`inputs`/`answer`, which are one-shot and parse as JSON. If you
+only want to watch a session, `plori attach --read-only` is the scriptable
+form, and redirecting either stdin or stdout already selects it.
+
 Wire-level acceptance cases live in [UAT.md](UAT.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plori/cli",
   "description": "plori (plori.ai): a cloud AI agent with its own computer - persistent disk, real CLI tools, and memory. The official plori CLI.",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "license": "MIT",
   "homepage": "https://plori.ai",
   "repository": {
@@ -26,10 +26,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@plori/cli-darwin-arm64": "0.2.6",
-    "@plori/cli-darwin-x64": "0.2.6",
-    "@plori/cli-linux-x64": "0.2.6",
-    "@plori/cli-linux-arm64": "0.2.6",
-    "@plori/cli-win32-x64": "0.2.6"
+    "@plori/cli-darwin-arm64": "0.3.0",
+    "@plori/cli-darwin-x64": "0.3.0",
+    "@plori/cli-linux-x64": "0.3.0",
+    "@plori/cli-linux-arm64": "0.3.0",
+    "@plori/cli-win32-x64": "0.3.0"
   }
 }