@topolo/cli 0.1.5 → 0.1.7

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`, `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,14 @@ 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 api <service> <method> <path>`
 
 Escape hatch for endpoints without typed modules yet.
@@ -98,6 +111,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 +153,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

package/dist/index.js

@@ -64,17 +64,38 @@ var TopoloHttpError = class extends TopoloSdkError {
     this.path = path;
   }
 };
-var DEFAULT_SERVICE_URLS = {
+var SERVICES = {
+  agent: "https://topolo-agent-worker.topolo.workers.dev",
   auth: "https://auth.topolo.app",
-  crm: "https://topolo-crm-worker.topolo.workers.dev"
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://r2-media-manager-worker.topolo.workers.dev",
+  chat: "https://chat.topolo.app",
+  commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  crm: "https://crm-api.topolo.app",
+  forecast: "https://forecast-worker-production.topolo.workers.dev",
+  learn: "https://topololearn-api.topolo.workers.dev",
+  mdm: "https://nodo-mdm-api.topolo.app",
+  messaging: "https://messages.topolo.app",
+  nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  one: "https://topoloone-worker.topolo.workers.dev",
+  pay: "https://topolo-pay.topolo.workers.dev",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper-api.topolo.app",
+  social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
+  socialize: "https://socialize-prod-api.topolo.workers.dev",
+  support: "https://support.topolo.app",
+  "web.api": "https://web-api.topolo.app",
+  "web.runtime": "https://sites.topolo.app"
 };
 var PLATFORM_SERVICE_IDS = {
   crm: "srv_iCwM4jGXcwlj"
 };
+var DEFAULT_SERVICE_URLS = SERVICES;
 function resolveServiceUrl(service, overrides) {
   const override = overrides?.[service];
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, "_").toUpperCase()}`;
   const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
   if (envValue) return envValue;
   return DEFAULT_SERVICE_URLS[service];
@@ -744,7 +765,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var CLI_VERSION = "0.1.4";
+var CLI_VERSION = "0.1.7";
 
 // src/client.ts
 async function buildClient(options) {
@@ -885,24 +906,33 @@ function formatContact(c) {
 }
 
 // src/commands/api.ts
-var KNOWN_SERVICES = ["auth", "crm"];
+var KNOWN_SERVICES = Object.keys(DEFAULT_SERVICE_URLS).sort();
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 var WRITE_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function registerApiCommand(program2) {
-  program2.command("api <service> <method> <path>").description("Generic passthrough to a Topolo service (escape hatch for untyped endpoints)").option("-d, --data <json>", "JSON body (for POST/PUT/PATCH)").option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
+  program2.command("api <service> <method> <path>").description(
+    `Generic passthrough to a Topolo service. Known services: ${KNOWN_SERVICES.join(", ")}.`
+  ).option("-d, --data <json>", "JSON body (for POST/PUT/PATCH)").option(
+    "-q, --query <kv...>",
+    "Query params as key=value (repeatable), e.g. --query source=cli page=2"
+  ).option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
     async (service, method, path, opts) => {
       const mode = resolveOutputMode(opts.json);
       try {
         const upperMethod = method.toUpperCase();
-        if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(upperMethod)) {
-          throw new Error(`Unsupported method: ${method}`);
+        if (!HTTP_METHODS.includes(upperMethod)) {
+          throw new Error(
+            `Unsupported method "${method}". Known: ${HTTP_METHODS.join(", ")}`
+          );
         }
+        const httpMethod = upperMethod;
         if (!KNOWN_SERVICES.includes(service)) {
           throw new Error(
             `Unknown service "${service}". Known services: ${KNOWN_SERVICES.join(", ")}`
           );
         }
-        if (WRITE_METHODS2.has(upperMethod) && !opts.confirm) {
-          throw new Error(`Mutating ${upperMethod} requires --confirm.`);
+        if (WRITE_METHODS2.has(httpMethod) && !opts.confirm) {
+          throw new Error(`Mutating ${httpMethod} requires --confirm.`);
         }
         let body = void 0;
         if (opts.data) {
@@ -912,6 +942,7 @@ function registerApiCommand(program2) {
             throw new Error("--data must be valid JSON");
           }
         }
+        const query = parseQueryPairs(opts.query);
         const topolo = await buildClient();
         if (!topolo) {
           throw new Error(
@@ -920,9 +951,10 @@ function registerApiCommand(program2) {
         }
         const result = await topolo.client.request({
           service,
-          method: upperMethod,
+          method: httpMethod,
           path,
           body,
+          ...query ? { query } : {},
           confirm: opts.confirm === true
         });
         emit(result, mode, () => JSON.stringify(result, null, 2));
@@ -932,6 +964,55 @@ function registerApiCommand(program2) {
     }
   );
 }
+function parseQueryPairs(pairs) {
+  if (!pairs || pairs.length === 0) return void 0;
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`Invalid --query entry "${pair}". Expected key=value.`);
+    }
+    const key = pair.slice(0, eq);
+    const value = pair.slice(eq + 1);
+    out[key] = value;
+  }
+  return out;
+}
+
+// src/commands/services.ts
+function registerServicesCommand(program2) {
+  program2.command("services").description("List every Topolo service the SDK can route to").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action((opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const rows = Object.keys(DEFAULT_SERVICE_URLS).sort().map((id) => {
+        const defaultUrl = DEFAULT_SERVICE_URLS[id];
+        const effectiveUrl = resolveServiceUrl(id);
+        return {
+          id,
+          defaultUrl,
+          effectiveUrl,
+          overridden: defaultUrl !== effectiveUrl
+        };
+      });
+      emit({ services: rows }, mode, () => formatRows(rows));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function formatRows(rows) {
+  const idWidth = Math.max(3, ...rows.map((r) => r.id.length));
+  const urlWidth = Math.max(7, ...rows.map((r) => r.effectiveUrl.length));
+  const lines = [];
+  lines.push(`${"ID".padEnd(idWidth)}  ${"URL".padEnd(urlWidth)}  OVERRIDE`);
+  lines.push(`${"-".repeat(idWidth)}  ${"-".repeat(urlWidth)}  --------`);
+  for (const r of rows) {
+    lines.push(
+      `${r.id.padEnd(idWidth)}  ${r.effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : ""}`
+    );
+  }
+  return lines.join("\n");
+}
 
 // src/index.ts
 var program = new Command();
@@ -942,6 +1023,7 @@ registerAuthCommands(program);
 registerWhoamiCommand(program);
 registerCrmCommands(program);
 registerApiCommand(program);
+registerServicesCommand(program);
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Command-line interface for the Topolo platform. Designed for humans and for agents (Claude, Codex, etc.) that prefer shell invocation.",
   "type": "module",
   "bin": {