@plori/cli 0.5.1 → 0.6.1

package/README.md

@@ -1,7 +1,8 @@
 # plori CLI
 
-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 runs AI agents that collaborate on one product in the cloud. Code,
+research, content: each works on its own copy, and Plori merges their changes
+back.
 
 `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.
@@ -77,22 +78,26 @@ 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.
+Both sign-in methods give the CLI the authority of the account owner:
+
+- **Browser login (`plori login`)** stores an OAuth session.
+- **API key (`plori login --key` or `PLORI_API_KEY`)** uses a key that you
+  create in the web app.
+
+With either sign-in, the CLI can do these things in the runs that you start:
+
+- approve an action
+- give a saved approval (`--always-allow`)
+- answer a secret question
+
+Saved approvals apply to these runs. With either sign-in, `plori workflows run`
+can also run a workflow that is not active, and `plori schedules create`
+activates a schedule immediately.
+
+A run that an MCP client started has stricter rules. In that run, the CLI can
+deny an approval request or answer a question. It cannot approve an action or
+give a saved approval. Approve the action in the web app. The refusal for an
+approval includes the web address to open.
 
 ## First Workspace
 
@@ -106,7 +111,9 @@ plori workspace run mate "Research this topic and save the result to work/report
 
 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.
+from `plori workspace list` if names are duplicated. The list includes your own
+and shared Workspaces, with `ACCOUNT` and `ROLE` columns. JSON includes
+`account` (`user_id`, `email`) and `role` (`owner`, `member` or `viewer`).
 
 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.
@@ -157,9 +164,9 @@ Approvals and input requests are answered where they appear: `y` or `n` for an
 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.
+In a run that an MCP client started, the server refuses `y` and `a` as described in
+[Which sign-in can approve actions](#which-sign-in-can-approve-actions).
+`n`, plain answers and secret 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 conversation
@@ -180,19 +187,26 @@ plori workspace run mate "build it" --follow  # stream the turn live (tools on s
 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 schedules create mate "daily report" --in 86400
+plori schedules list mate
+plori schedules cancel mate <schedule-id>
 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
+plori workflow list --workspace mate
+plori workflow create "rss digest" --workspace mate --trigger cron --cron "0 9 * * *"
+plori workflow run "rss digest" --workspace mate  # run it now (real fire, billed)
+plori workflow execution "rss digest" <exec-id> --workspace mate  # poll one run
 ```
 
+Use `plori input answer <run-id> <tool-call-id> --value -` to read an answer from stdin.
+
+Schedules take a Workspace name or UUID. `plori workflow create` requires `--workspace`.
+Build the draft with `plori workspace run mate "Build the steps for workflow <id>"`.
+
 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 conversation attach` is the one exception: it is a live
@@ -206,6 +220,21 @@ the exit codes are listed under [Agent-driven use](#agent-driven-use).
 `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.
 
+An idle conversation starts a run. If it is running, the server accepts plain text as
+steering or queues it. The CLI prints the receipt and exits `0`, including with
+`--follow`. It does not wait for the running or paused run to end. The receipt
+contains `status` (`steering` or `queued`), `steer_id` and `run_id`, plus the
+conversation and Workspace ids. That `run_id` identifies the running or paused
+run, not a result for this message. Use `plori runs list "$AGENT_ID"` to find a
+later queued turn. There is no lookup from `steer_id` to that later run.
+
+If the paused run has exactly one ordinary question assigned to you, the message
+answers it. Otherwise it queues, with `pending_inputs` identifying the request
+and assignee. Sending a message does not cancel a pending request.
+`409 conversation_busy` still applies to attachments or run options in a busy
+conversation, and to working-copy conflicts. Send attachments and options when
+idle.
+
 ### Start a run and keep working
 
 A local agent (a Claude Code or Codex shell, an orchestrator) does not have to
@@ -256,8 +285,8 @@ them per agent. An approval that gates an outward-facing write carries a
 `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.
+`--always-allow` work with either sign-in, except in a run that an MCP client
+started: the server refuses them there and the owner approves in the web app.
 
 ### Machine-readable streams
 
@@ -273,7 +302,7 @@ tools return: `run_id`, `status`, `session_id`, `url`, `pending_inputs`.
 
 | code | meaning |
 | ---- | ------- |
-| 0 | the command succeeded; a run that was waited for completed |
+| 0 | the command succeeded. A waited run completed, or the server accepted a message as steering or queued |
 | 1 | API or runtime failure |
 | 2 | usage error |
 | 3 | missing, rejected, or expired credentials |
@@ -330,7 +359,8 @@ retry when its storage is ready.
 
 `--max-tokens` sets a token figure that is recorded on the new group, in
 cache-weighted tokens. The default is 2,000,000. The figure does not limit model
-calls; the account's credit balance is the only spend limit. To add the worker to
+calls. The account's credit balance limits spend. A member can also have a
+monthly spend cap that refuses new run starts with `402`. To add the worker to
 an existing group, use `--task-group <id>` without `--max-tokens`.
 
 The command prints the worker ID and a `worker status` command on stderr. It
@@ -416,18 +446,26 @@ capability API and is not implemented by this command.
 JSON configuration and resolutions accept inline JSON or
 `@file` (`@-` reads stdin).
 
+Plori merges a finished worker's saved changes into the Workspace files
+automatically when they merge cleanly. This includes workers started through the
+CLI, MCP or REST. The manager resolves conflicts. Failed or stopped workers keep
+their saved revisions without an automatic merge. The same applies while a
+worker waits for input. The manager can still submit those saved revisions.
+
+Use the changeset commands below for conflicts or saved work that did not land.
 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.
+content reuses an earlier revision. A clean changeset merges automatically.
 
-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
+For conflicts, the manager submits the same saved revision and resolves the
+conflicts. To resolve them yourself, write the copy that `changeset get` returns
+as `integration_working_copy_id`. Use ETag checks. Then use
 `changeset resolve --generation N --resolutions @resolutions.json` with records
 such as `[{"path":"notes.txt","expected_etag":17,"summary":"Reviewed merge"}]`.
+Read the resolved comparison before accepting it. Its current revision is the
+Workspace revision that the comparison used. `changeset accept` requires that
+comparison-current ID and accepts repeated `--evidence` flags.
 Resolve, accept and reject each require their own stable idempotency key.
 
 List workers and task groups, read charged costs, and inspect retention:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plori/cli",
-  "description": "Plori runs AI agents in Workspaces.",
-  "version": "0.5.1",
+  "description": "Plori runs AI agents that collaborate on one product in the cloud.",
+  "version": "0.6.1",
   "license": "MIT",
   "homepage": "https://plori.ai",
   "repository": {
@@ -26,10 +26,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@plori/cli-darwin-arm64": "0.5.1",
-    "@plori/cli-darwin-x64": "0.5.1",
-    "@plori/cli-linux-x64": "0.5.1",
-    "@plori/cli-linux-arm64": "0.5.1",
-    "@plori/cli-win32-x64": "0.5.1"
+    "@plori/cli-darwin-arm64": "0.6.1",
+    "@plori/cli-darwin-x64": "0.6.1",
+    "@plori/cli-linux-x64": "0.6.1",
+    "@plori/cli-linux-arm64": "0.6.1",
+    "@plori/cli-win32-x64": "0.6.1"
   }
 }