@divergeai/cli 0.1.14 → 0.1.23

package/README.md

@@ -13,16 +13,34 @@ diverge tools list --organization-id <id>
 
 Node 22 or later. Linux and macOS are supported; Windows is best-effort.
 
+`diverge --help`, `diverge <command> --help` and `diverge <command> <verb>
+--help` print the usage, and that usage is the CLI's command table: a
+command, verb or option that does not exist is answered with the closest ones
+it lists, by spelling or by what their description says (`diverge whoami` →
+`diverge status`, `tools search` → `tools list --filter`), and exits 1.
+
 ## Sign in
 
 `diverge login` runs the browser sign-in (authorization code with PKCE on a
 loopback listener). The browser only authenticates you; the organization is
 chosen afterwards in the CLI, never through the browser: `--organization-id
-<id|name>` if given, else the last login's, else your only membership, else a
-menu. The login is bound to that organization on the platform, and `diverge
-org use <id|name>` switches without a browser. The login is cached in
-`~/.diverge/token.json` (mode 0600), refreshes itself, and `diverge logout`
-revokes it on the platform before forgetting it.
+<id|name>` if given, else the last login's, else your only organization, else
+a menu. The organizations offered are the ones you may act in: your
+memberships, and for a platform actor every organization. That organization is the default — where commands that name none act —
+and `diverge org use <id|name>` changes it. The login itself is yours, not an
+organization's: every token is issued for the organization a command acts
+in. The login is cached in
+`~/.diverge/logins/<deployment>/login.json` (mode 0600) and refreshes itself:
+each use extends it by seven days, never past thirty days from sign-in, and `diverge logout`
+revokes it on the platform before forgetting it. `diverge status` shows both:
+the idle expiry and the thirty-day end; after that every command exits 6 and says to run `diverge
+login`.
+
+The login is shared by every shell and agent on the machine, and so is the
+default. To work in another organization without changing it, name it on the
+command — `--organization-id <id>` or `DIVERGENT_ORG_ID`: the CLI gets a token
+for that organization from the login and caches it beside the others. The
+platform grants it only where your roles back the login's scopes.
 
 - `diverge status` shows the deployment, the organization, the scopes, and a
   `Tool execution:` line naming who a tool call would run as: you, or a
@@ -37,15 +55,19 @@ revokes it on the platform before forgetting it.
   which one; it signs that account in instead of reusing whatever session the
   browser holds and issues nothing to any other. Without `--as` the account
   of the last login is kept, so switching accounts is always explicit.
-- A login also remembers its scopes: without `--scopes` the next login asks
-  for the same ones, so a routine re-login never narrows what the CLI may do.
-  A token carries only what was asked at sign-in; the Forge scopes
-  (`forge:read forge:write`) are what the Forge lanes need.
-- `diverge token` prints a fresh access token and nothing else. It is the
-  credential helper Claude Code and Codex call, so an agent never holds a
-  long-lived key.
-- `diverge login --api-url <url>` targets another deployment and remembers it;
-  `DIVERGENT_API_URL` overrides per shell.
+- Without `--scopes` a login asks for the scopes the platform registers for
+  this CLI — everything it and Forge use — and holds what your roles grant,
+  so a routine re-login never narrows what another session relies on. The
+  platform re-reads that registration on every refresh: a scope added there
+  reaches your login without a new CLI or a new sign-in. `--scopes` asks for
+  less, deliberately, and that login stays exactly that narrow.
+- `diverge token [--organization-id <id>]` prints a fresh access token and
+  nothing else. It is the credential helper Claude Code, Codex and `forge`
+  call, so an agent never holds a long-lived key.
+- Each deployment keeps its own login. `diverge login --api-url <url>` signs
+  in to another one (a test stack) beside the production login; commands
+  reach it when `DIVERGENT_API_URL` names it. Nothing on disk chooses the
+  deployment.
 
 ## Coding agents
 
@@ -113,15 +135,17 @@ shows it how, file-based arguments and batches included.
 ## Platform tools
 
 Every command takes the scope it acts in: `--organization-id` (or
-`DIVERGENT_ORG_ID`, else the organization the login was issued to) and, for a
+`DIVERGENT_ORG_ID`, else the login's organization; another one gets its own
+token without moving the login) and, for a
 resource inside a project, `--project-id` (or `DIVERGENT_PROJECT_ID`).
 
 ```bash
-diverge tools list --filter rbac             # find candidates
+diverge tools list --filter rbac             # find candidates by name or description
 diverge tools describe rbac_assign_role      # one schema, on demand
 diverge tools call rbac_list_roles --args-json '{}'
+diverge tools call rbac_list_roles --json    # exactly one JSON outcome on stdout, errors included
 diverge tools call inventory_lookup_stock --args-file args.json   # or --args-json - to read stdin
-diverge tools run calls.json --wait          # several calls from one file, one JSON line of outcome each
+diverge tools run calls.json --wait          # several calls from one file (- for stdin), one JSON line of outcome each
 ```
 
 Put arguments in a file or on stdin when a shell may touch them: Windows
@@ -132,7 +156,8 @@ order, and exits with the worst outcome: 1 failed, 4 rejected, 5 expired,
 
 A write that needs a human is not refused: it is persisted as a pending
 invocation, decided in the platform's approval inbox, and read back here by
-id. Branch on the exit code, never on text:
+id. Branch on the exit code, never on text; `call`, `run` and `invocation <id>`
+give the same code for the same status, with or without `--json`:
 
 | code | meaning |
 | --- | --- |
@@ -140,6 +165,7 @@ id. Branch on the exit code, never on text:
 | 3 | pending: hand over the link, read it back later with `diverge tools invocation <id>` (add `--wait` to stay attached) |
 | 4 | rejected, with the operator's reason |
 | 5 | expired: raise a fresh call, the old id is final |
+| 6 | the login expired or was revoked: run `diverge login`; retrying will not help |
 | 1 | failure, including approved-but-failed |
 
 The CLI raises and reads; it never decides. `diverge tools bridge` serves the
@@ -182,7 +208,7 @@ non-interactive shells, under `CI`, and with `DIVERGE_NO_UPDATE_CHECK=1`.
 
 | variable | effect |
 | --- | --- |
-| `DIVERGENT_API_URL` | the deployment for this shell |
+| `DIVERGENT_API_URL` | the deployment for this shell; production when unset |
 | `DIVERGE_HOME` | state directory, default `~/.diverge` |
 | `DIVERGENT_ORG_ID`, `DIVERGENT_PROJECT_ID` | tool scope when the flags are omitted; without either, the login's organization |
 | `DIVERGENT_CLIENT_ID`, `DIVERGENT_CLIENT_SECRET`, `DIVERGENT_USER_ID` | unattended tool execution with service credentials, delegated to that person |