@topolo/cli 0.1.32 → 0.2.1

package/README.md

@@ -7,10 +7,12 @@ via `stdin`/`stdout`.
 ## Current scope
 
 - API-key authentication (long-lived, service-scoped).
-- Access-token authentication via OAuth device flow when a CLI OAuth client id is configured.
-- Stored access-token refresh when the config includes a refresh token and OAuth client id.
-- First-class `production` and `staging` CLI environments with separate stored credentials, OAuth client ids, and service URL overrides.
-- Commands: `auth login/logout/status`, `whoami`, `apps`, `apps scaffold`, `oauth clients`, `integrations prompt/check`, `services`, credential-scoped `actions`, and generic `api` passthrough for SDK-registered services.
+- OAuth device-flow sign-in with a **built-in first-party client** — `topolo auth login` needs no client id; any Topolo user can sign in.
+- Stored access-token refresh; the `@topolo/mcp` server reads the same credential, so agents need no API-key plumbing.
+- First-class `production`, `staging`, `development`, and `local` environments with separate stored credentials and service URL overrides.
+- **Per-context credentials** — hold and switch between your personal space and multiple organizations with `topolo context`.
+- **One-command agent setup** — `topolo skills install` wires the skill + MCP into Claude Code / Codex.
+- Commands: `auth`, `whoami`, `context`, `skills`, `apps`, `services`, credential-scoped `actions`, generic `api` passthrough, and internal `platform` scaffolding.
 
 ## Install
 
@@ -32,7 +34,7 @@ Production is the default. Select staging with `--env staging` anywhere in the c
 
 ```bash
 topolo auth status --env staging --json
-topolo auth login --env staging --client-id doac_...
+topolo auth login --env staging
 topolo platform apps scaffold home --env staging --write --json
 ```
 
@@ -41,21 +43,47 @@ The staging profile uses `auth.stg.topolo.us`, `developers.stg.topolo.us`, and `
 For interactive use:
 
 ```bash
-topolo auth login --client-id doac_...  # device flow
-topolo auth login --api-key topo_live_... # store API key directly
-topolo auth status           # shows which source is active
-topolo auth logout           # clears the stored credential
+topolo auth login             # OAuth device flow — no client id needed; approve in the browser
+topolo auth login --api-key topo_live_...  # or store an API key directly (headless/service)
+topolo auth status            # shows which source is active
+topolo auth logout            # clears the stored credential
 ```
 
-If no client id is configured, `topolo auth login` falls back to an API-key
-prompt in an interactive terminal. Non-interactive sessions should pass
-`--api-key` or set `TOPOLO_PRODUCTION_CLI_CLIENT_ID`,
-`TOPOLO_STAGING_CLI_CLIENT_ID`, or the shared `TOPOLO_CLI_CLIENT_ID`.
+`topolo auth login` uses a **built-in first-party OAuth client per environment**,
+so any Topolo user can sign in without registering a client — what they can do
+is decided by their permissions. `--client-id doac_...` (or
+`TOPOLO_CLI_CLIENT_ID` / `TOPOLO_<ENV>_CLI_CLIENT_ID`) is only for advanced /
+self-hosted setups. Headless installs use `--api-key`.
+
+### Contexts
+
+A user can act in their personal space or any organization they belong to. Each
+context has its own credential; the CLI (and the MCP) run in the active one.
+These credentials are independent from the shared web preference: switching a
+CLI/MCP context never moves the browser session, and a web switch never changes
+an already-issued CLI/MCP token or its refresh chain.
+
+```bash
+topolo context ls                          # personal + your orgs, and which is active
+topolo context use <organization|personal> # switch (validated + a fresh token minted server-side)
+```
+
+### Wire into Claude Code / Codex
+
+```bash
+topolo skills install    # copies the skill + registers the `topolo` MCP server, credential-free
+```
+
+The MCP reads the same credential `topolo auth login` writes — no API key to paste.
 
 ## Cross-org isolation
 
 The CLI **never accepts an `orgId` argument**. Every command is scoped to the
-organization embedded in the credential. This is enforced in two places:
+active context embedded in the credential (personal or a specific org); to act
+in a different organization you switch context with `topolo context use`, which
+mints a new context-scoped credential — you can never target another org by
+passing an id. The context remains bound through refresh rotation and is not
+re-hydrated from the user's current web selection. This is enforced in two places:
 
 1. The SDK does not expose any `orgId` parameter on any public method.
 2. Each Topolo backend app re-derives `orgId` from the credential on every request and binds it to SQL query filters.
@@ -80,7 +108,7 @@ request. Dynamic action calls and the generic `topolo api` passthrough enforce
 this too:
 
 ```bash
-topolo actions call topolo_mail_messages_send --data '{"mailboxId":"primary","subject":"Hello"}' --confirm
+topolo actions call app_topolo_mail.messages.send --data '{"mailboxId":"primary","subject":"Hello"}' --confirm
 topolo api mail POST /api/mail/mailboxes/primary/messages --data '{"subject":"Hello"}' --confirm
 ```
 
@@ -114,16 +142,15 @@ organization and credential the relevant permissions.
 
 ### `topolo actions`
 
-Lists the callable actions available to the current credential. Applications
+Searches one application's callable actions for the current credential. Applications
 publish actions through Topolo Developers, Auth filters them by the same
 service permissions already used by API keys, launchers, and backend services,
 and the CLI calls them through the shared SDK.
 
 ```bash
-topolo actions --json
 topolo actions --service mail --json
-topolo actions get topolo_mail_messages_send --json
-topolo actions call topolo_mail_messages_send \
+topolo actions get app_topolo_mail.messages.send --json
+topolo actions call app_topolo_mail.messages.send \
   --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
   --confirm --json
 ```
@@ -132,6 +159,20 @@ Use `topolo actions` before `topolo api` when an app has published a machine
 contract for the operation. `topolo api` remains the escape hatch for endpoints
 that are not yet in the action catalog.
 
+Workspace-scoped actions carry resource context independently from the active
+personal/organization credential and independently from the browser session:
+
+```bash
+topolo actions call app_topolo_inventory.dashboard.get \
+  --resource-type workspace \
+  --resource-id <workspace_id> \
+  --data '{}' --json
+```
+
+Both resource flags are required together. This supports concurrent agent
+operations across many app-local workspaces without changing the CLI/MCP org
+context or the user's web switcher.
+
 ### `topolo apps`
 
 Lists launchable Topolo applications available to the current credential. This
@@ -223,7 +264,7 @@ topolo api auth GET /api/me
 topolo api mail POST /api/mail/mailboxes/primary/messages --data '{"subject":"Hello"}' --confirm
 ```
 
-Use `topolo services --json` to discover service ids permitted for the current
+Use `topolo services --json` to discover app ids permitted for the current
 credential before calling a service that does not have a typed command yet.
 
 ## Output modes