@topolo/cli 0.1.6 → 0.1.8

package/README.md

@@ -4,12 +4,12 @@ Command-line interface for the Topolo platform. Designed for both humans and
 third-party agents (Claude Code, Codex, Cursor, etc.) that prefer to interact
 via `stdin`/`stdout`.
 
-## Phase 1 scope
+## Current scope
 
 - API-key authentication (long-lived, service-scoped).
-- Access-token authentication (short-lived, cross-service — used for dev/testing).
-- Commands: `auth login/logout/status`, `whoami`, `crm contacts:list`, `crm contacts:get`, generic `api` passthrough.
-- OAuth2 authorization-code + device flows will arrive in Phase 2; until then, `auth login` expects a paste-in API key minted at the Topolo Developers console.
+- 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.
+- Commands: `auth login/logout/status`, `whoami`, `apps`, `apps scaffold`, `services`, `crm contacts:list`, `crm contacts:get`, and generic `api` passthrough for SDK-registered services.
 
 ## Install
 
@@ -30,11 +30,16 @@ Credentials come from (in priority order):
 For interactive use:
 
 ```bash
-topolo auth login            # prompts for API key
+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
 ```
 
+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_CLI_CLIENT_ID`.
+
 ## Cross-org isolation
 
 The CLI **never accepts an `orgId` argument**. Every command is scoped to the
@@ -89,6 +94,46 @@ topolo crm contacts:list -q "acme" -p 2 -s 50 --json
 topolo crm contacts:get contact_abc123
 ```
 
+### `topolo services`
+
+Lists every service id and effective URL known to the generated SDK registry.
+
+```bash
+topolo services --json
+```
+
+### `topolo apps`
+
+Lists every Topolo application known to the generated SDK catalog, including
+pages-only applications that do not expose a callable API service.
+
+```bash
+topolo apps --json
+topolo apps get mail --json
+topolo apps requirements mail --json
+topolo apps audit mail --json
+topolo apps audit mail --local --repo-root /Users/ashes/Projects/topolo --fail-on needs_review --json
+topolo apps scaffold insights --json
+topolo apps scaffold insights --workflow-only --no-json
+```
+
+Agents should call `topolo apps requirements <app> --json` before creating or
+expanding a Topolo app. The output is the versioned platform contract for app
+metadata, canonical docs, shared auth, shared shell, service registration,
+deployment metadata, agent surfaces, observability, and verification.
+`topolo apps audit --json` turns the same contract into per-app scores and a
+catalog-backed migration queue. Add `--local --repo-root <topolo-checkout>` to
+include filesystem evidence from the app repo, CloudControl metadata, and
+TopoloDocs. Add `--fail-on needs_review` for the default new-work gate, or
+`--fail-on partial` for strict release readiness.
+
+`topolo apps scaffold <app>` generates the required new-application scaffold
+manifest, including expected package/auth/shell/docs/CloudControl files and a
+`topolo-conformance.yml` GitHub Actions workflow. The generated workflow checks
+out the app under `PlatformApplications/<AppDir>`, checks out `Topolo-io/docs`,
+`Topolo-io/topolo-sdk`, and `Topolo-io/TopoloCli`, builds the current CLI from
+source, then runs the local conformance audit with `--fail-on needs_review`.
+
 ### `topolo api <service> <method> <path>`
 
 Escape hatch for endpoints without typed modules yet.
@@ -98,6 +143,9 @@ topolo api auth GET /api/me
 topolo api crm POST /api/contacts --data '{"first":"Jane"}' --confirm
 ```
 
+Use `topolo services --json` to discover valid service ids before calling a
+service that does not have a typed command yet.
+
 ## Output modes
 
 - Pretty when stdout is a TTY.
@@ -137,6 +185,10 @@ Both docs cover the same CLI surface: credential handling, the JSON invocation
 contract, the write-safety `--confirm` guardrail, and the cross-org isolation
 rules. Keep them in sync when adding new commands.
 
+For agents that support MCP, also register `@topolo/mcp`; the skill/AGENTS
+guidance still matters because it tells the agent when to prefer MCP tools,
+when to fall back to shell commands, and how to handle writes.
+
 ## Debug output
 
 Set `TOPOLO_DEBUG=1` to trace every SDK request to stderr (stdout stays clean