@overaihq/cli 0.9.1 → 0.11.1

package/README.md

@@ -20,7 +20,7 @@ overai workspace list           # find a workspace id
 overai workspace show <id>      # read its name and overview
 overai workspace users <id>     # list users and direct/inherited roles
 overai create agent --workspace <id> --name "Support agent"
-overai clone <workspaceId>      # materialize resources and WORKSPACE.md
+overai clone <workspaceId>      # clone the workspace and its descendants
 # ...edit files...
 overai status                   # local edits + remote drift
 overai diff                     # what changed
@@ -36,6 +36,17 @@ Run `overai help` for the full command list, including function invocation,
 automation runs and per-node state, tablespace SQL (a psql-style REPL), and
 `overai dev` for live-previewing a web page from local files.
 
+Clone includes accessible, non-archived descendants in nested
+`workspaces/<slug>.<workspaceId>/` folders. Each workspace has its own
+`.overai/manifest.json`, resource files, and `WORKSPACE.md`. Existing resource
+filenames and the top-level clone directory stay unchanged.
+
+Commands use the nearest workspace folder: `cd` into a child to edit or sync it.
+`status`, `pull`, `push`, `deploy`, and `restore` still affect only that workspace,
+not its descendants. Pull does not discover new child workspaces. Clone those
+separately, or clone the parent into a fresh directory. Local file moves never
+move resources between workspaces in OverAI.
+
 Inside a clone, `workspace show` and `workspace users` infer the workspace id.
 `WORKSPACE.md` is the overview captured when the clone is created; use
 `workspace show` when you need the current server value.
@@ -48,6 +59,31 @@ clone/push/deploy. Runtime commands include `agent generate`, `data-stream
 append|query`, `data-file upload|download|head`, `integration configure|config`,
 and `printable-page render`; `overai help` shows their arguments.
 
+## Working across organizations
+
+Each backend and organization has an independent saved CLI session. Work in
+separate workspace folders: commands automatically use the clone’s organization.
+For commands outside a clone, use `OVERAI_ORG_ID=<orgId> overai <command>` or set
+the shell variable. `org switch <orgId>` changes the machine-global default for
+unscoped commands; it leaves other org sessions intact.
+
+Missing org sessions are established from an eligible saved CLI login. SSO requires
+browser authorization: run `OVERAI_ORG_ID=<orgId> overai signin`. Ordinary commands
+never launch a browser. `whoami` shows the backend, org, identity, and selection
+source; `org list` also indicates which orgs have saved sessions.
+
+`signout` revokes the effective org’s CLI session. `signout --all` revokes all sessions
+saved by this installation, across backends, without signing out browsers or other
+machines. Failed revocations retain credentials for retry. Clone sync commands reject
+an `OVERAI_ORG_ID` that disagrees with the clone.
+
+Existing credentials migrate automatically. Credentials for different backends are
+never exchanged between them; custom deployments remember `OVERAI_APP_URL` at signin.
+One identity per backend is supported. An older CLI login whose legacy org switch
+removed its CLI session tag needs browser sign-in before it can establish sibling
+sessions. The new CLI requires a backend supporting `establishCliOrgSession` for
+automatic org entry and never falls back to a destructive switch.
+
 ## Passing queries, JSON, and scripts
 
 Arguments that carry a whole document rather than a scalar also accept `@<file>`