@divergeai/cli 0.1.2

package/README.md

@@ -0,0 +1,168 @@
+# diverge
+
+The Divergent platform CLI: sign in, point coding agents at the platform's
+model gateway, and call platform tools as yourself.
+
+```bash
+npm install -g @divergeai/cli
+diverge login                        # opens the browser; choose your organization
+diverge agents setup claude          # Claude Code on the gateway
+diverge agents run dsh -- --profile web --port 3131 --no-open
+diverge tools list --organization-id <id>
+```
+
+Node 22 or later. Linux and macOS are supported; Windows is best-effort.
+
+## Sign in
+
+`diverge login` runs the browser sign-in (authorization code with PKCE on a
+loopback listener). A login serves exactly one organization: without
+`--organization-id` the platform asks you to choose. The login is cached in
+`~/.diverge/token.json` (mode 0600), refreshes itself, and `diverge logout`
+revokes it on the platform before forgetting it.
+
+- `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
+  delegated `DIVERGENT_USER_ID` through service credentials. Read it before
+  granting anything.
+- The CLI names the account it acts as — `Signed in as:` on `login` and
+  `status`, `Acting as:` before every `tools` request — because a token
+  names only a user id and the wrong account is invisible without the email:
+  use the operator account for operator work, and the break-glass account
+  only knowingly.
+- A login is for one account. `diverge login --as <email>` tells the platform
+  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.
+
+## Coding agents
+
+`diverge agents setup <agent>` writes the configuration one agent needs to use
+the gateway, keeping everything else in the file:
+
+| agent | what is written |
+| --- | --- |
+| `claude` | `~/.claude/settings.json` (or `./.claude/settings.local.json` with `--scope project`): the gateway base URL and `diverge token` as the key helper; `--project-id` adds the project header, `--model-discovery` lets Claude Code list the gateway's models |
+| `opencode` | `~/.config/opencode/opencode.json`: a `divergent-<surface>` provider reading `DIVERGENT_TOKEN` |
+| `codex` | `~/.codex/config.toml`: a `divergent` provider block with `diverge token` as its auth command; `--print` shows it instead |
+| `dsh` | `$DSH_HOME/divergent-<surface>.yml`: a patch overlay with the models the gateway serves, dsh's DeepSeek adapter, telemetry upload and search turned off, and the platform's web search served over `diverge tools bridge` (row `mcp-divergent`) |
+
+`diverge agents run dsh` launches DeepSeek Harness on the overlay and keeps
+its token fresh in dsh's own credentials file until it exits. With nothing
+else it starts dsh's web UI and prints the URL; `diverge agents run dsh --
+"<task>"` answers one task headless and exits; anything after `--` goes to
+dsh as given.
+
+`diverge agents status` shows the organization, the scopes, and the models
+each surface serves. `diverge agents rotate` keeps a token file fresh
+(default `~/.divergent/token`, every 600 seconds; `--once` writes and exits)
+for a client that reads a file or an environment substitution rather than
+running a helper.
+
+### Web search
+
+Claude Code and Codex search through their model vendor's own server tool,
+which the gateway forwards unchanged when the organization's upstream is
+Anthropic or OpenAI. Every other model, dsh included, searches through the
+platform's `search_online` tool: one key on the platform, metered and audited
+per organization. The dsh overlay wires it in as `mcp__divergent__search_online`
+(dsh's DeepSeek-backed `web_search` needs a vendor key and is off; `web_fetch`
+stays). In dsh's web profile the shipped agent presets still list `web_search`,
+where a patch cannot reach; it fails loudly and the model uses the bridge's
+tool listed beside it. To give Claude Code or Codex the same tool for a
+non-native upstream, register the bridge once:
+
+```bash
+claude mcp add --scope user divergent -- diverge tools bridge --tools search_online
+```
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.divergent]
+command = "diverge"
+args = ["tools", "bridge", "--tools", "search_online"]
+```
+
+## 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
+resource inside a project, `--project-id` (or `DIVERGENT_PROJECT_ID`).
+
+```bash
+diverge tools list --filter rbac             # find candidates
+diverge tools describe rbac_assign_role      # one schema, on demand
+diverge tools call rbac_list_roles --args-json '{}'
+```
+
+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:
+
+| code | meaning |
+| --- | --- |
+| 0 | executed, or approved and executed |
+| 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 |
+| 1 | failure, including approved-but-failed |
+
+The CLI raises and reads; it never decides. `diverge tools bridge` serves the
+same catalog as a stdio MCP server for clients without a shell, with
+`divergent_invocation_status` for the read-back. `--tools <name,name>` publishes
+and accepts only those tools: the whole catalog is tens of thousands of tokens
+on every request, so a harness gets the tools it was given and nothing else.
+
+## Tenant plugins
+
+A tenant plugin is a plugin whose code runs in your organization's own
+runtime and never inside the platform: the platform knows it through a
+manifest (`@divergent/plugin-contract`), enables it per organization, and
+reaches it through your bridge binding. See
+[RFC: Tenant Plugins](../../docs/rfcs/rfc-tenant-plugins.md).
+
+```bash
+diverge plugins validate manifest.json     # dry run: every problem the platform would refuse, at once
+diverge plugins publish  manifest.json     # forge_plugins:create in the login's organization
+diverge plugins list
+diverge plugins retire <pluginId>          # the descriptor and its tools go; installations stay
+```
+
+Tools are pinned to the manifest: a change is a new version published again.
+After publishing, enable the plugin with `forge_set_plugin_state` (or the
+Forge Routing page) and bind the runtime with a bridge binding whose
+`runtimeType` equals the manifest's `runtime.type`; declare `networkPolicy`
+on the binding when the endpoint is a tailnet or LAN address.
+
+## Updating
+
+`diverge update` installs the latest release with the npm that installed it.
+
+## Environment
+
+| variable | effect |
+| --- | --- |
+| `DIVERGENT_API_URL` | the deployment for this shell |
+| `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 |
+| `DSH_HOME` | where dsh keeps its files, default `~/.dsh` |
+
+## Security
+
+Public OAuth client with PKCE; a sign-in carries the scopes your roles back
+at the organization and omits the rest (`diverge login` says which); access tokens live one hour; refresh tokens
+rotate and a replay revokes the session; the cache is written with mode 0600
+from its first byte; `logout` revokes on the platform; every request carries
+`User-Agent: diverge/<version>`, which the platform records as the calling
+client. The package carries no secret. Released from GitHub Actions by npm
+trusted publishing, so no publish token exists.