@plori/cli 0.4.2 → 0.5.0

package/README.md

@@ -1,11 +1,13 @@
 # plori CLI
 
-`plori` drives your hosted agents (each one a persistent cloud environment with
-its own disk, tools, and memory) from a terminal or a script. It is the CLI+skills
-counterpart to the remote MCP server at `https://api.plori.ai/mcp`: same
-account, same agents, same REST API underneath, and the commands mirror the
-MCP tool names (create_agent → `create`, invoke_agent → `run`,
-get_run_result → `result`, …).
+Plori runs AI agents in Workspaces. Several agents can work on one project at
+once, and Plori merges their changes back into the Workspace.
+
+`plori` manages hosted agents and Workspaces from a terminal or script. It uses
+the public HTTP API directly with your account credentials. MCP is not required.
+`plori workspace create` creates a Workspace and its agent. `plori workspace run` sends
+that agent a task on the Workspace files. To run several workers in one Workspace, use the
+[Workspace coordination](#workspace-coordination) commands.
 
 ## Install
 
@@ -59,7 +61,7 @@ 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.
+credentials when needed.
 
 For CI or another headless environment, keep using an API key created at
 <https://plori.ai/dashboard/settings>:
@@ -71,34 +73,70 @@ 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`.
+API server, e.g. a local `uat-server`.
+
+### Which sign-in can approve actions
+
+The server treats the two credentials differently:
+
+- **Browser login (`plori login`)** stores an OAuth session. It can deny an
+  approval request and answer a plain question. A run that you start with it
+  pauses before each action outside the agent's environment, such as a git
+  push, a deploy or an email. You approve each action in the web app. Saved
+  approvals do not apply to that run. It cannot approve an action, grant saved approval
+  (`--always-allow`), answer a secret question, or run or activate a workflow
+  that is not active. The server refuses these requests. Each refusal, except
+  the one for saved approval, includes the web address where the account
+  owner decides. A schedule created with this sign-in waits until the owner
+  confirms it at its `confirm_url` in the web app.
+- **API key (`plori login --key` or `PLORI_API_KEY`)** is the owner's own
+  credential. With it, `input answer --approve` and `--always-allow` work from the
+  terminal, `schedules create` activates the schedule at once, and `workflow run` can run
+  a workflow that is not active.
+
+## First Workspace
+
+Start with a Workspace:
+
+```sh
+plori login
+plori workspace create mate
+plori workspace run mate "Research this topic and save the result to work/report.md"
+```
+
+Creation prints an idempotency key. Reuse it with `--idempotency-key` when you
+retry the same request. A name can identify more than one Workspace. Use its ID
+from `plori workspace list` if names are duplicated.
+
+For commands that take an agent, set `AGENT_ID` to the creation response's
+`default_manager_agent_id`. The Workspace name is not an agent name.
 
 ## 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
+`plori conversation attach` opens a live conversation in your terminal: the recent history, a
+prompt, streaming output, and pending requests in one place. It is the same
+conversation 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 environment. Nothing on your
+**The terminal does not give the agent access to your local files.** The shell
+and the Workspace files are in the agent's own cloud environment. 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
+plori conversation attach "$AGENT_ID"  # the agent's most recent conversation
+plori conversation attach "$AGENT_ID" --session <id>  # a specific conversation of that agent
+plori conversation attach "$AGENT_ID" --history 50  # replay 50 turns instead of the default 20
+plori conversation attach "$AGENT_ID" --read-only  # tail it, no prompt
+plori conversation attach "$AGENT_ID" --verbose  # also print reasoning and tool results
 ```
 
-The argument is an agent name, an agent id, or a session id, so a session id
+The argument is an agent name, an agent id, or a conversation id, so a conversation 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
+`PLORI_BASE_URL`) points attach at a non-production API server, like every
 other command.
 
 While attached:
@@ -110,63 +148,63 @@ While attached:
   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
+- The slash commands are `/sessions` (list this agent's conversations), `/new`
+  (start one), `/model <slug>` (change the model), `/web` (print this conversation'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
+approval, `a` to answer yes and grant saved 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.
+After a browser login, the server refuses `y`, `a` and secret answers as
+described in [Which sign-in can approve actions](#which-sign-in-can-approve-actions).
+`n` and plain answers work with either credential.
 
 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
+stdin or stdout is redirected, attach drops the prompt and tails the conversation
+instead, so `plori conversation attach "$AGENT_ID" | 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
+answer, so a request that arrives during one is printed with the conversation'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
-plori result mate <run-id> --wait        # wait for it later
-plori run mate "build it" --follow       # stream the turn live (tools on stderr)
-echo "summarize this" | plori run mate -  # message from stdin
-plori watch --agent mate                 # one JSON line per run ending
-plori inbox                              # what ended, and what waits on you
-plori schedule mate "daily report" --in 86400
-plori inputs mate                        # runs paused on a human question
-plori answer <run-id> <tool-call-id> --approve
-plori answer <run-id> <tool-call-id> --approve --always-allow  # + stop asking for this tool
-plori credits && plori disk
-
-plori workflows list                     # all your workflows
-plori workflows list --agent mate        # one agent's (use "none" for unassigned)
-plori workflows create "rss digest" --trigger cron --cron "0 9 * * *"
-plori workflows run "rss digest"         # run it now (real fire, billed)
-plori workflows execution "rss digest" <exec-id>   # poll one run
+plori conversation attach "$AGENT_ID"  # open the live conversation (interactive)
+plori workspace run mate "clone repo X and run the tests"
+plori workspace run mate "long job" --no-wait  # returns a run id immediately
+plori runs status "$AGENT_ID" <run-id> --wait  # wait for it later
+plori workspace run mate "build it" --follow  # stream the turn live (tools on stderr)
+echo "summarize this" | plori workspace run mate -  # message from stdin
+plori account watch --agent "$AGENT_ID"  # one JSON line per run ending
+plori account inbox  # what ended, and what waits on you
+plori schedules create "$AGENT_ID" "daily report" --in 86400
+plori input list "$AGENT_ID"  # runs paused on an approval or a question
+plori input answer <run-id> <tool-call-id> --approve
+plori input answer <run-id> <tool-call-id> --approve --always-allow  # + stop asking for this tool
+plori account balance && plori account disk
+
+plori workflow list  # all your workflows
+plori workflow list --agent "$AGENT_ID"  # one agent's (use "none" for unassigned)
+plori workflow create "rss digest" --trigger cron --cron "0 9 * * *"
+plori workflow run "rss digest"  # run it now (real fire, billed)
+plori workflow 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. `plori attach` is the one exception: it is a live
+can parse without flags. `plori conversation 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. `plori watch` is the other:
+redirected stream turns it into a read-only tail. `plori account watch` is the other:
 its output is a stream of JSON lines in every mode. Errors go to stderr, and
 the exit codes are listed under [Agent-driven use](#agent-driven-use).
 
 ## Agent-driven use
 
-The reply text of `plori run` is the only thing written to stdout (tool
-narration streams to stderr), so a calling agent can pipe it directly. Prefer
-one long-lived agent (`create` returns the existing agent for a reused name)
-over creating new ones.
+`plori workspace run` prints the reply in a terminal and a JSON result when piped.
+Tool progress goes to stderr. Reuse the Workspace for later tasks.
 
 ### Start a run and keep working
 
@@ -175,12 +213,12 @@ wait out a run. Start it, go on to something else, and let the CLI report the
 ending:
 
 ```sh
-plori run mate "long job" --no-wait   # returns the run id at once
-plori watch --agent mate              # one JSON line per ending; run it in the background
-plori inbox                           # what ended since you last acknowledged
+plori workspace run mate "long job" --no-wait  # returns the run id at once
+plori account watch --agent "$AGENT_ID"  # one JSON line per ending; run it in the background
+plori account inbox  # what ended since you last acknowledged
 ```
 
-`plori watch` holds a connection to the run-event feed and prints one JSON
+`plori account watch` holds a connection to the run-event feed and prints one JSON
 object per line, unchanged, until you stop it with Ctrl-C or SIGTERM (exit 0).
 A dropped connection is reopened with a delay that starts at one second and
 doubles to thirty, and the reconnect asks for everything after the last line it
@@ -204,25 +242,26 @@ event of every selected run in a `data` field. The flags:
 
 ### Catch up in one shot
 
-`plori inbox` is the same information without a long-lived process: the runs
+`plori account inbox` is the same information without a long-lived process: the runs
 that ended since your last acknowledgement, plus everything waiting on a human.
-`plori inbox --ack <run-id>` moves the watermark to that run's ending, so the
+`plori account inbox --ack <run-id>` moves the watermark to that run's ending, so the
 next inbox starts after it. The watermark is local and per account, stored next
 to your credentials in `~/.config/plori/inbox.json`.
 
 ### Answer what is waiting
 
 A run that pauses on a human approval reports `status: "awaiting_input"` and
-carries the rows to answer in its `pending_inputs`; `plori inputs <agent>` lists
+carries the rows to answer in its `pending_inputs`; `plori input list <agent>` lists
 them per agent. An approval that gates an outward-facing write carries a
-`consent_tool` (visible in `plori inputs --json`); answering it with
-`--always-allow` also grants a standing consent so the agent stops asking for
-that tool. That is the human's call to make, not the calling agent's; on a row
-without a `consent_tool` the flag grants nothing.
+`consent_tool` (visible in `plori input list --json`); answering it with
+`--always-allow` also lets the agent use that tool without asking again. That is the human's call to make, not the calling agent's; on a row
+without a `consent_tool` the flag grants nothing. `--approve` and
+`--always-allow` need an API-key sign-in. After a browser login, the server
+refuses them and the owner approves in the web app.
 
 ### Machine-readable streams
 
-`plori run --jsonl` replaces the rendered stream with one JSON object per line
+`plori workspace run --jsonl` replaces the rendered stream with one JSON object per line
 (`message_delta`, `tool_call`, `tool_result`, `step`, `awaiting_input`, `done`,
 `error`), and ends with the run result on one more line, tagged
 `"type":"result"`.
@@ -238,14 +277,14 @@ tools return: `run_id`, `status`, `session_id`, `url`, `pending_inputs`.
 | 1 | API or runtime failure |
 | 2 | usage error |
 | 3 | missing, rejected, or expired credentials |
-| 4 | the control plane could not be reached |
+| 4 | the API server could not be reached |
 | 10 | the run is waiting on a human answer |
 | 20 | the run ended in error |
 | 30 | the run was cancelled |
 | 40 | the wait ran out with the run still going |
 
-`plori run`, `plori result --wait` (bounded by `--wait-seconds`) and
-`plori watch` all report these codes. Waiting goes through the session socket,
+`plori workspace run`, `plori runs status --wait` (bounded by `--wait-seconds`) and
+`plori account watch` all report these codes. Waiting goes through the conversation socket,
 so exit 4 means the CLI could not watch the run, not that the run failed: the
 run keeps going on the server either way.
 Exit 3 and exit 4 also print one JSON object on stdout,
@@ -254,11 +293,168 @@ reading the stream sees why it stopped.
 
 ### What not to use
 
-`plori attach` is for a human at a terminal: it takes over the keyboard and
+`plori conversation 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`/`watch`/`inbox`/`inputs`/`answer`, which either parse as JSON or
-stream JSON lines. If you only want to follow one session's output,
-`plori attach --read-only` is the scriptable form, and redirecting either stdin
+`workspace run`, `runs status`, `account watch`, `account inbox`, `input list` and `input answer`, which either parse as JSON or
+stream JSON lines. If you only want to follow one conversation's output,
+`plori conversation attach --read-only` is the scriptable form, and redirecting either stdin
 or stdout already selects it.
 
 Wire-level acceptance cases live in the godog UAT suite at [`uat/`](../uat/) (`make uat`).
+
+## Workspace coordination
+
+These commands coordinate workers in a Workspace. See the
+[Workspace guide](https://plori.ai/docs/workspaces) for the task flow and recovery limits.
+
+Use `workspace`, `worker` and `changeset` for Workspace work. `plori advanced help`
+lists the storage and agent commands. Advanced storage commands take exact IDs.
+Workspace commands and worker start/list/status/stop also accept a unique Workspace name.
+There is no implicit active Workspace.
+
+For older agents, see [agents created before Workspaces](https://plori.ai/docs/workspaces#what-about-agents-created-before-workspaces).
+
+### Start one worker
+
+After you sign in, create a Workspace and give a worker a task:
+
+```sh
+plori workspace create project
+plori worker start project 'Update the selected files' --wait
+```
+
+`worker start` makes a copy of the latest saved revision, creates a task group,
+and starts the worker. It waits for the copy to be ready, for up to 600 seconds.
+Use `--timeout` to change that limit. If the Workspace has no saved revision yet,
+retry when its storage is ready.
+
+`--max-tokens` sets the new group's limit in cache-weighted tokens. The default
+is 2,000,000. To share an existing group's limit, use `--task-group <id>` without
+`--max-tokens`.
+
+The command prints the worker ID and a `worker status` command on stderr. It
+also prints a generated idempotency key if you omit `--idempotency-key`.
+Retry with the same key and task if a request is interrupted.
+
+`--wait` waits for the run. A completed run returns its reply and the worker's `save_state`.
+Run completion does not mean the files are saved or merged. `--wait-seconds`
+sets the run wait limit; it defaults to `--timeout`. Use `worker status --wait`
+to wait again. Follow the advanced procedure below to review and merge the changes.
+
+### Advanced: prepare copies and merge changes
+
+Create a Workspace. Every Workspace has its own agent. `--manager ID` is the id
+of an existing agent to use as the Workspace's agent. Without it, the command
+creates a new one. The Workspace's agent does not run until it receives a
+message:
+
+```sh
+plori workspace create project --idempotency-key project-create-1
+plori workspace get "$WORKSPACE_ID"
+plori advanced copy list "$WORKSPACE_ID"
+plori advanced copy checkpoint "$WORKSPACE_ID" "$COPY_ID" --idempotency-key checkpoint-1
+plori advanced operation wait "$WORKSPACE_ID" "$OPERATION_ID" --timeout 120
+plori advanced copy clone "$WORKSPACE_ID" --base-revision "$REVISION_ID" --idempotency-key clone-1
+```
+
+Use IDs from the returned JSON. `advanced copy clone` makes a writable copy from a
+revision, and `advanced copy checkpoint` saves a copy as a new revision.
+`advanced independent-agent list` lists every agent of the account, including the agents
+that `advanced independent-agent create` made. `plori advanced agent list` leaves those out.
+A clone or checkpoint can return `provisioning`.
+Wait for that operation to become `ready` before using its result. List commands
+for copies, revisions and changesets accept `--cursor` and `--limit`. Continue
+with the returned `next_cursor`.
+
+Start a worker on a ready copy:
+
+```sh
+plori advanced task-group create "$WORKSPACE_ID" --max-tokens 2000000 --idempotency-key task-1
+plori advanced worker spawn "$WORKSPACE_ID" 'Update the selected files' --name worker-1 \
+  --copy "$WORKER_COPY_ID" --task-group "$GROUP_ID" --idempotency-key worker-1
+plori worker status "$WORKSPACE_ID" "$REQUEST_ID" --wait --wait-seconds 600
+```
+
+`--max-tokens` is the group's shared limit in cache-weighted tokens. It must
+be positive. Starting a worker reserves one full context window plus output
+from this limit, so 2,000,000 tokens covers one worker. Raise the limit when
+several workers share the group.
+Spawn returns a request. Status returns the run result when it is available,
+with the worker's save and review state. A finished run does not mean its files
+are saved. `--executor` is the id of an existing agent to run as the worker.
+`--name` starts a new agent as the worker. To give a worker more work, run `advanced worker spawn`
+again with the same `--executor` and `--session` and a ready copy. The original
+copy can be reused after it is released. A new clone does not continue the
+earlier work exactly. If the run pauses for an approval or a question, reply
+with `input answer` and follow the run it returns with `runs status`. Worker status does
+not include a web URL.
+
+Advanced storage mutations require `--idempotency-key`. Workspace creation, runs and worker starts
+generate a key when you omit it. Reuse the
+same key and request when retrying. Do not reuse a key for changed input.
+Optional worker callbacks use `--callback-url`. Prefer the
+`PLORI_WORKER_CALLBACK_SECRET` environment variable over `--callback-secret`,
+which can appear in process listings. Callback fields require the server's
+Workspace worker callback support.
+
+Read and write a selected copy without starting a run:
+
+```sh
+plori advanced workspace-files read "$WORKSPACE_ID" /notes.txt --copy "$COPY_ID"
+plori advanced workspace-files write "$WORKSPACE_ID" /notes.txt --copy "$COPY_ID" \
+  --file ./notes.txt --if-match "$ETAG"
+```
+
+Read JSON includes the ETag. Use `--if-match 0` only to create a missing file.
+A stale version fails instead of overwriting another edit. `--file -` reads stdin.
+`--revision` selects an immutable revision for list/stat/read. The text API
+refuses binary files. Use `advanced workspace-files read-bytes` with `--revision` for
+immutable media. It returns base64 JSON and the ETag, including
+in a terminal, with an 8 MiB limit. Mutable-copy binary download uses a separate
+capability API and is not implemented by this command.
+
+JSON configuration and resolutions accept inline JSON or
+`@file` (`@-` reads stdin).
+
+Submit a changeset with `--base-revision`, `--incoming-revision` and
+`--current-revision`. The optional `--incoming-save-operation` identifies the
+selected save receipt. Automated clients preserve this identity when unchanged
+content reuses an earlier revision.
+
+Read the comparison before accepting. Its current revision is the Workspace
+revision that the comparison used. `changeset accept` requires that
+comparison-current ID and accepts repeated `--evidence` flags.
+For conflicts, write the copy that `changeset get` returns as
+`integration_working_copy_id`, with ETag checks, then use
+`changeset resolve --generation N --resolutions @resolutions.json` with records
+such as `[{"path":"notes.txt","expected_etag":17,"summary":"Reviewed merge"}]`.
+Resolve, accept and reject each require their own stable idempotency key.
+
+List workers and task groups, read charged costs, and inspect retention:
+
+```sh
+plori worker list "$WORKSPACE_ID" --task-group "$GROUP_ID" --limit 25
+plori advanced task-group list "$WORKSPACE_ID"
+plori workspace costs "$WORKSPACE_ID" --from 2026-09-01T00:00:00Z
+plori advanced task-group costs "$GROUP_ID"
+plori advanced workspace retention "$WORKSPACE_ID" --view pins
+```
+
+Cost output is the API JSON. A null or missing amount is unknown, not zero, and a
+task group's token limit is not a cost. `resources` is one page of observations. Continue
+it with `--resource-cursor`. An expired retention state means the item can be
+removed, not that it is already deleted. `advanced workspace pin` keeps a copy or changeset
+until `--expires-at` and needs `--kind`, `--resource` and `--idempotency-key`.
+Pins work only when the Workspace's retention policy sets a pin limit. `advanced workspace unpin`
+releases a pin. `advanced workspace update --retention-profile p --retention-version n`
+moves the Workspace to Plori's current retention policy for new copies and
+revisions. `p` and `n` must name that current policy.
+
+`advanced agent stop` and `advanced task-group stop` stop running work and keep history and files.
+`advanced agent retire` stops an agent from getting new work. Workspace deletion permanently
+erases its history and files. Copy/revision deletion removes the selected
+resource. Retirement and deletion require `--yes` in scripts, or interactive
+confirmation. An accepted deletion starts cleanup. It does not prove physical
+erasure. Existing exit codes also apply to waited worker runs: 10 for an
+approval or a question, 20 for run error, 30 for cancellation and 40 for
+timeout.

package/package.json

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