@topolo/cli 0.1.34 → 0.2.1

package/dist/index.js

@@ -50,6 +50,12 @@ var TopoloPermissionError = class extends TopoloSdkError {
     this.required = required;
   }
 };
+var TopoloConfirmationRequiredError = class extends TopoloSdkError {
+  constructor(message) {
+    super("confirmation_required", message);
+    this.name = "TopoloConfirmationRequiredError";
+  }
+};
 var TopoloHttpError = class extends TopoloSdkError {
   status;
   body;
@@ -1112,6 +1118,7 @@ var APPLICATIONS = {
           "topolo.io"
         ],
         "routes": [
+          "one.topolo.io",
           "topolo.io",
           "www.topolo.io"
         ],
@@ -2065,7 +2072,6 @@ var TOPOLO_RESOURCE_TYPE_HEADER = "X-Topolo-Resource-Type";
 var TOPOLO_RESOURCE_ID_HEADER = "X-Topolo-Resource-ID";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
-var CATALOG_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
@@ -2074,9 +2080,9 @@ var TopoloClient = class _TopoloClient {
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
+  refreshCredential;
+  refreshInFlight = null;
   debug;
-  serviceCatalogCache = null;
-  actionCatalogCache = null;
   /**
    * Process-wide cache for slug → app-id lookups. Keyed by
    * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
@@ -2101,6 +2107,7 @@ var TopoloClient = class _TopoloClient {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
+    this.refreshCredential = options.refreshCredential;
     this.debug = options.debug;
   }
   emit(event) {
@@ -2118,11 +2125,11 @@ var TopoloClient = class _TopoloClient {
   async request(opts) {
     const method = opts.method ?? "GET";
     if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
-      throw new TopoloAuthError(
+      throw new TopoloConfirmationRequiredError(
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
       );
     }
-    const resolvedService = await this.resolveRequestService(opts.service);
+    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: requireHttpOrigin(opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
     if (opts.query) {
@@ -2153,20 +2160,36 @@ var TopoloClient = class _TopoloClient {
       headers.set(TOPOLO_RESOURCE_TYPE_HEADER, resourceType);
       headers.set(TOPOLO_RESOURCE_ID_HEADER, resourceId);
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
-    const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
     const urlStr = url.toString();
     const startedAt = Date.now();
     this.emit({ phase: "request", method, service: resolvedService.serviceKey, path: opts.path, url: urlStr, requestId });
+    const fetchOnce = async () => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+      const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+      try {
+        return await this.fetchImpl(urlStr, {
+          method,
+          headers: new Headers(headers),
+          body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+          signal
+        });
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    };
     let res;
     try {
-      res = await this.fetchImpl(urlStr, {
-        method,
-        headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
-        signal
-      });
+      const attemptedCredential = this.credential;
+      res = await fetchOnce();
+      if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
+        await res.body?.cancel().catch(() => void 0);
+        const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
+        if (refreshed) {
+          applyAuthHeaders(headers, refreshed);
+          res = await fetchOnce();
+        }
+      }
     } catch (err) {
       this.emit({
         phase: "error",
@@ -2179,8 +2202,6 @@ var TopoloClient = class _TopoloClient {
         error: err instanceof Error ? err.message : String(err)
       });
       throw err;
-    } finally {
-      clearTimeout(timeoutId);
     }
     const contentType = res.headers.get("Content-Type") ?? "";
     const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
@@ -2219,6 +2240,19 @@ var TopoloClient = class _TopoloClient {
     });
     return parsed;
   }
+  async refreshRejectedAccessToken(attemptedAccessToken) {
+    if (this.credential.kind === "access_token" && this.credential.accessToken !== attemptedAccessToken) {
+      return this.credential;
+    }
+    if (!this.refreshCredential) return null;
+    this.refreshInFlight ??= this.refreshCredential().then((credential) => {
+      if (credential) this.credential = credential;
+      return credential;
+    }).catch(() => null).finally(() => {
+      this.refreshInFlight = null;
+    });
+    return this.refreshInFlight;
+  }
   async resolveRequestService(service) {
     const serviceKey = normalizeLookupKey(service);
     if (!serviceKey) {
@@ -2244,9 +2278,8 @@ var TopoloClient = class _TopoloClient {
     );
   }
   async resolveLiveCallableService(serviceKey) {
-    const catalog = await this.listServices();
-    const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match) return null;
+    const match = await this.getService(serviceKey).catch(() => null);
+    if (!match || !catalogEntryMatches(match, serviceKey)) return null;
     const baseUrl = resolveCatalogServiceUrl(match, {
       serviceKey,
       overrides: this.serviceUrls
@@ -2320,12 +2353,13 @@ var TopoloClient = class _TopoloClient {
    * The live Auth catalog is the authority because it is scoped to the caller's
    * organization and effective permissions.
    */
-  async listServices() {
-    const now = Date.now();
-    if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
-      return this.serviceCatalogCache.entries;
-    }
-    const res = await this.request({ service: "developers", method: "GET", path: "/api/services/catalog" });
+  async searchServices(options = {}) {
+    const res = await this.request({
+      service: "developers",
+      method: "GET",
+      path: "/api/services/catalog",
+      query: catalogSearchQuery(options)
+    });
     const raw = res.data?.services ?? res.services;
     if (!Array.isArray(raw)) {
       throw new TopoloSdkError(
@@ -2335,6 +2369,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
+      if (!isRecord(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -2359,11 +2394,30 @@ var TopoloClient = class _TopoloClient {
         apiKeyResources
       });
     }
-    this.serviceCatalogCache = {
-      entries,
-      expiresAt: now + CATALOG_CACHE_TTL_MS
-    };
-    return entries;
+    const page = normalizeCatalogPage(
+      res.data?.page ?? res.page
+    );
+    return { services: entries, page };
+  }
+  /** @deprecated Prefer searchServices() so callers retain the continuation cursor. */
+  async listServices(options = {}) {
+    return (await this.searchServices(options)).services;
+  }
+  async getService(application) {
+    const needle = application.trim();
+    if (!needle) throw new TopoloSdkError("unknown_service", "application is required");
+    const res = await this.request({
+      service: "developers",
+      method: "GET",
+      path: "/api/services/catalog",
+      query: { application: needle }
+    });
+    const raw = res.data?.application ?? res.application;
+    const entry = normalizeServiceCatalogEntry(raw);
+    if (!entry) {
+      throw new TopoloSdkError("unknown_service", `Unknown Topolo application "${application}".`);
+    }
+    return entry;
   }
   /**
    * List callable actions from the live registry-canonical catalog (definitions
@@ -2371,16 +2425,15 @@ var TopoloClient = class _TopoloClient {
    * caller's organization and effective permissions; no bundled/static app
    * action list is used as an authorization source.
    */
-  async listActions(options = {}) {
-    const now = Date.now();
-    if (!options.service && this.actionCatalogCache && this.actionCatalogCache.expiresAt > now) {
-      return this.actionCatalogCache.entries;
+  async searchActions(options) {
+    if (!options.service?.trim()) {
+      throw new TopoloSdkError("service_required", "service is required for bounded action discovery");
     }
     const res = await this.request({
       service: "developers",
       method: "GET",
       path: "/api/actions/catalog",
-      ...options.service ? { query: { service: options.service } } : {}
+      query: { service: options.service, ...catalogSearchQuery(options) }
     });
     const raw = res.data?.actions ?? res.actions;
     if (!Array.isArray(raw)) {
@@ -2390,36 +2443,96 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
-    if (!options.service) {
-      this.actionCatalogCache = {
-        entries,
-        expiresAt: now + CATALOG_CACHE_TTL_MS
-      };
+    return {
+      actions: entries,
+      page: normalizeCatalogPage(
+        res.data?.page ?? res.page
+      )
+    };
+  }
+  async getActionCatalogSummary(service) {
+    const boundedService = service.trim();
+    if (!boundedService) {
+      throw new TopoloSdkError("service_required", "service is required for bounded action discovery");
     }
-    return entries;
+    const res = await this.request({
+      service: "developers",
+      method: "GET",
+      path: "/api/actions/catalog",
+      query: { service: boundedService, summary: "true" }
+    });
+    const raw = res.data?.summary ?? res.summary;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is unavailable.");
+    }
+    const record = raw;
+    if (record.algorithm !== "sha256-v1" || typeof record.digest !== "string" || !/^[a-f0-9]{64}$/.test(record.digest) || !Number.isSafeInteger(record.actionCount) || Number(record.actionCount) < 0) {
+      throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is invalid.");
+    }
+    return {
+      algorithm: "sha256-v1",
+      digest: record.digest,
+      actionCount: Number(record.actionCount)
+    };
+  }
+  /** @deprecated Prefer searchActions() so callers retain the continuation cursor. */
+  async listActions(options) {
+    if (!options) {
+      throw new TopoloSdkError("service_required", "service is required for bounded action discovery");
+    }
+    return (await this.searchActions(options)).actions;
   }
   async getAction(action) {
-    const needle = normalizeActionLookupKey(action);
-    const actions = await this.listActions();
-    const match = actions.find((entry) => actionEntryMatches(entry, needle));
-    if (!match) {
+    const actionId = action.trim();
+    if (!actionId) {
       throw new TopoloSdkError(
         "unknown_action",
-        `Unknown Topolo action "${action}". Run action discovery first and pass an action id, name, or tool name.`
+        "action id is required"
       );
     }
+    let res;
+    try {
+      res = await this.request({
+        service: "developers",
+        method: "GET",
+        path: "/api/actions/catalog",
+        query: { actionId }
+      });
+    } catch (error) {
+      if (error instanceof TopoloHttpError && error.status === 404) {
+        throw new TopoloSdkError("unknown_action", `Unknown or unavailable Topolo action "${action}".`);
+      }
+      throw error;
+    }
+    const raw = res.data?.action ?? res.action;
+    const match = normalizeActionCatalogEntry(raw);
+    if (!match) throw new TopoloSdkError("unknown_action", `Unknown or unavailable Topolo action "${action}".`);
     return match;
   }
   async callAction(action, input2 = {}, options = {}) {
     const entry = await this.getAction(action);
+    const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
+    if (agentAccess === "off") {
+      throw new TopoloPermissionError(
+        `Topolo action "${entry.actionId}" is not available for agent invocation.`,
+        entry.requiredPermission ? [entry.requiredPermission] : []
+      );
+    }
+    if ((agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive) && options.confirm !== true) {
+      throw new TopoloConfirmationRequiredError(
+        `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
+      );
+    }
     const mapped = mapActionInput(entry, input2);
     const service = entry.appSlug || entry.appId;
     return this.request({
       service,
+      ...entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {},
       method: entry.method,
       path: mapped.path,
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
+      ...options.resource ? { resource: options.resource } : {},
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
@@ -2557,6 +2670,18 @@ function serviceKeyCandidates2(slug) {
 function normalizeLookupKey(value) {
   return String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
 }
+function requireHttpOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_action_target", `Invalid action API origin "${value}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password) {
+    throw new TopoloSdkError("invalid_action_target", `Invalid action API origin "${value}".`);
+  }
+  return url.origin;
+}
 function deriveDevelopersFromAuth(authUrl) {
   if (!authUrl) return null;
   try {
@@ -2583,6 +2708,47 @@ function catalogEntryLookupKeys(entry) {
   }
   return [...keys];
 }
+function catalogSearchQuery(options) {
+  const query = {};
+  if (typeof options.query === "string" && options.query.trim()) query.query = options.query.trim();
+  if (typeof options.cursor === "string" && options.cursor.trim()) query.cursor = options.cursor.trim();
+  if (typeof options.limit === "number" && Number.isFinite(options.limit)) query.limit = Math.trunc(options.limit);
+  return query;
+}
+function normalizeCatalogPage(value) {
+  if (!isRecord(value)) return { nextCursor: null, hasMore: false };
+  return {
+    nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
+    hasMore: value.hasMore === true
+  };
+}
+function normalizeServiceCatalogEntry(item) {
+  if (!isRecord(item)) return null;
+  const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
+  if (!appId) return null;
+  const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
+    (permission) => typeof permission === "string" && permission.trim().length > 0
+  ) : [];
+  const catalogApiKeyResources = normalizeApiKeyResourceMetadataList(
+    item.api_key_resources ?? item.apiKeyResources
+  );
+  const apiKeyResource = normalizeApiKeyResourceMetadata(item.api_key_resource ?? item.apiKeyResource) ?? catalogApiKeyResources[0] ?? null;
+  const apiKeyResources = catalogApiKeyResources.length > 0 ? catalogApiKeyResources : apiKeyResource ? [apiKeyResource] : [];
+  return {
+    appId,
+    slug: typeof item.app_slug === "string" ? item.app_slug : null,
+    name: typeof item.name === "string" ? item.name : null,
+    description: typeof item.description === "string" ? item.description : null,
+    apiBaseUrl: typeof item.api_base_url === "string" ? item.api_base_url : typeof item.apiBaseUrl === "string" ? item.apiBaseUrl : null,
+    launchUrl: typeof item.launch_url === "string" ? item.launch_url : typeof item.launchUrl === "string" ? item.launchUrl : null,
+    status: typeof item.status === "string" ? item.status : null,
+    surfaceKind: typeof item.surface_kind === "string" ? item.surface_kind : null,
+    launchable: item.launchable === true,
+    permissions,
+    apiKeyResource,
+    apiKeyResources
+  };
+}
 function normalizeActionCatalogEntry(item) {
   if (!item || typeof item !== "object" || Array.isArray(item)) return null;
   const a = item;
@@ -2596,6 +2762,8 @@ function normalizeActionCatalogEntry(item) {
   }
   return {
     actionId,
+    target: pickActionString(a.target_key) ?? pickActionString(a.target) ?? null,
+    apiBaseUrl: pickActionString(a.api_base_url) ?? pickActionString(a.apiBaseUrl) ?? null,
     name,
     toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
     title: pickActionString(a.title) ?? name,
@@ -2607,6 +2775,7 @@ function normalizeActionCatalogEntry(item) {
     path: path4,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
     requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? "",
+    authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
     outputSchema: plainObject(a.output_schema ?? a.outputSchema),
     readOnly: Boolean(a.read_only ?? a.readOnly),
@@ -2626,16 +2795,12 @@ function pickActionString(value) {
 function pickAgentAccess(value) {
   return value === "auto" || value === "confirm" || value === "off" ? value : null;
 }
+function pickAuthorizationMode(value) {
+  return value === "runtime" ? "runtime" : "static";
+}
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
-function normalizeActionLookupKey(value) {
-  return String(value || "").trim().toLowerCase();
-}
-function actionEntryMatches(entry, needle) {
-  if (!needle) return false;
-  return [entry.actionId, entry.name, entry.toolName].filter((value) => typeof value === "string" && value.length > 0).some((value) => value.toLowerCase() === needle);
-}
 function mapActionInput(action, input2) {
   const remaining = { ...input2 || {} };
   const path4 = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
@@ -3039,6 +3204,9 @@ var TopoloOAuth2 = class {
     return parsed;
   }
 };
+function contextKey(contextType, organizationId) {
+  return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
+}
 var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
   production: {
     developers: "https://developers.topolo.app"
@@ -3132,6 +3300,28 @@ function writeProfileConfig(config, environment, profile) {
   };
   return { ...config, profiles };
 }
+function writeContextCredential(config, environment, ctx, makeActive = true) {
+  const key = contextKey(ctx.contextType, ctx.organizationId);
+  const profile = profileForEnvironment(config, environment);
+  const contexts = { ...profile.contexts ?? {}, [key]: ctx };
+  const next = { contexts };
+  if (makeActive) {
+    next.activeContext = key;
+    next.credential = ctx.credential;
+    next.oauthClientId = ctx.oauthClientId ?? profile.oauthClientId;
+  }
+  return writeProfileConfig(config, environment, next);
+}
+function activateContext(config, environment, key) {
+  const profile = profileForEnvironment(config, environment);
+  const ctx = profile.contexts?.[key];
+  if (!ctx) return config;
+  return writeProfileConfig(config, environment, {
+    activeContext: key,
+    credential: ctx.credential,
+    oauthClientId: ctx.oauthClientId ?? profile.oauthClientId
+  });
+}
 function clearProfileCredential(config, environment) {
   const next = { ...config };
   if (environment === "production") {
@@ -3163,7 +3353,7 @@ async function resolveCredential(environment = selectedEnvironment()) {
   return profileForEnvironment(config, environment).credential ?? null;
 }
 var REFRESH_SKEW_SECONDS = 60;
-async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
+async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
   const prefix = envVarPrefix(environment);
   if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
     return resolveCredential(environment);
@@ -3174,7 +3364,7 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
   if (!cred || cred.kind !== "access_token") return cred ?? null;
   if (!cred.refreshToken || !cred.expiresAt || !profile.oauthClientId) return cred;
   const now = Math.floor(Date.now() / 1e3);
-  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  if (!options.force && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
   try {
     const oauth = new TopoloOAuth2({
       serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
@@ -3189,9 +3379,20 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
       ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
       expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
     };
-    await writeConfig(
-      environment === "production" && !config.profiles?.production ? { ...config, credential: refreshed } : writeProfileConfig(config, environment, { credential: refreshed })
-    );
+    const activeContext = profile.activeContext;
+    const activeEntry = activeContext ? profile.contexts?.[activeContext] : void 0;
+    const updated = activeContext && activeEntry ? writeProfileConfig(config, environment, {
+      credential: refreshed,
+      contexts: {
+        ...profile.contexts ?? {},
+        [activeContext]: {
+          ...activeEntry,
+          credential: refreshed,
+          oauthClientId: activeEntry.oauthClientId ?? profile.oauthClientId
+        }
+      }
+    }) : environment === "production" && !config.profiles?.production ? { ...config, credential: refreshed } : writeProfileConfig(config, environment, { credential: refreshed });
+    await writeConfig(updated);
     return refreshed;
   } catch {
     return cred;
@@ -3243,7 +3444,14 @@ function oauthClientRegistrationUrl(environment = selectedEnvironment()) {
 function apiKeyIssuanceUrl(environment = selectedEnvironment()) {
   return `${developerConsoleUrl(environment)}/credentials`;
 }
-var DEFAULT_CLI_CLIENT_IDS = {};
+var DEFAULT_CLI_CLIENT_IDS = {
+  // First-party `topolo-cli` device-flow client, seeded per environment by Auth
+  // (core/TopoloAuth/scripts/seed-first-party-oauth-clients.sql). Each env's
+  // Auth must have this client before the CLI ships pointing at it.
+  production: "topolo-cli",
+  staging: "topolo-cli",
+  development: "topolo-cli"
+};
 function resolveOAuthClientId(config, environment = selectedEnvironment()) {
   const envSpecific = process.env[`${envVarPrefix(environment)}_CLI_CLIENT_ID`];
   if (envSpecific) return envSpecific;
@@ -3301,18 +3509,43 @@ function normalizeError(err) {
     const code = err.code;
     const hintMap = {
       auth_error: "Run `topolo auth login` or set TOPOLO_API_KEY.",
+      confirmation_required: "Review the action and rerun with --confirm to allow it.",
       permission_denied: "Check your API key scopes or role assignments in TopoloDevelopers."
     };
     return {
       message: err.message,
       code,
       hint: code ? hintMap[code] : void 0,
-      exitCode: code === "auth_error" ? 2 : code === "permission_denied" ? 3 : 1
+      exitCode: code === "auth_error" || code === "confirmation_required" ? 2 : code === "permission_denied" ? 3 : 1
     };
   }
   return { message: String(err), exitCode: 1 };
 }
 
+// src/version.ts
+import { readFileSync } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function readCliVersion() {
+  try {
+    const here = dirname2(fileURLToPath(import.meta.url));
+    const candidates = [
+      join2(here, "package.json"),
+      join2(here, "..", "package.json")
+    ];
+    for (const path4 of candidates) {
+      try {
+        const pkg = JSON.parse(readFileSync(path4, "utf8"));
+        if (typeof pkg.version === "string" && pkg.version) return pkg.version;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+var CLI_VERSION = readCliVersion();
+
 // src/commands/auth.ts
 function registerAuthCommands(program2) {
   const auth = program2.command("auth").description("Manage Topolo credentials");
@@ -3450,18 +3683,15 @@ async function runDeviceFlow(options) {
   } finally {
     spinner?.stop();
   }
+  const credential = {
+    kind: "access_token",
+    accessToken: token.access_token,
+    ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
+    expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
+  };
+  const context = await resolveLoginContext(credential, resolved.serviceUrls, options.clientId);
   const updated = await readConfig();
-  await writeConfig(
-    writeProfileConfig(updated, options.environment, {
-      credential: {
-        kind: "access_token",
-        accessToken: token.access_token,
-        ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
-        expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
-      },
-      oauthClientId: options.clientId
-    })
-  );
+  await writeConfig(writeContextCredential(updated, options.environment, context));
   emit(
     {
       ok: true,
@@ -3476,6 +3706,29 @@ async function runDeviceFlow(options) {
     () => "\n  \u2713 Signed in. Run `topolo whoami` to see your identity."
   );
 }
+async function resolveLoginContext(credential, serviceUrls, clientId) {
+  try {
+    const topolo = createTopolo({
+      credential,
+      agent: { clientName: "topolo-cli", clientVersion: CLI_VERSION },
+      serviceUrls
+    });
+    const me = await topolo.identity.whoami();
+    const org = me.organization;
+    if (org?.id) {
+      return {
+        contextType: "organization",
+        organizationId: org.id,
+        organizationSlug: org.slug,
+        organizationName: org.name,
+        credential,
+        oauthClientId: clientId
+      };
+    }
+  } catch {
+  }
+  return { contextType: "personal", credential, oauthClientId: clientId };
+}
 function tryOpenBrowser(url) {
   try {
     const os = platform2();
@@ -3540,30 +3793,6 @@ function sleep(ms) {
   return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 
-// src/version.ts
-import { readFileSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-import { fileURLToPath } from "url";
-function readCliVersion() {
-  try {
-    const here = dirname2(fileURLToPath(import.meta.url));
-    const candidates = [
-      join2(here, "package.json"),
-      join2(here, "..", "package.json")
-    ];
-    for (const path4 of candidates) {
-      try {
-        const pkg = JSON.parse(readFileSync(path4, "utf8"));
-        if (typeof pkg.version === "string" && pkg.version) return pkg.version;
-      } catch {
-      }
-    }
-  } catch {
-  }
-  return "0.0.0";
-}
-var CLI_VERSION = readCliVersion();
-
 // src/client.ts
 async function buildClient(options) {
   const environment = selectedEnvironment();
@@ -3580,6 +3809,7 @@ async function buildClient(options) {
     },
     serviceUrls: profile.serviceUrls,
     requireConfirmForWrites: options?.requireConfirmForWrites,
+    ...credential.kind === "access_token" && credential.refreshToken ? { refreshCredential: () => refreshCredentialIfNeeded(environment, { force: true }) } : {},
     ...isDebugEnabled() ? { debug: stderrDebugLogger } : {}
   });
 }
@@ -3642,93 +3872,6 @@ function formatPretty(info) {
   return lines.join("\n");
 }
 
-// src/commands/actions.ts
-function registerActionsCommand(program2) {
-  const actions = program2.command("actions").description("List and call permission-scoped Topolo actions from the live catalog").option("-s, --service <service>", "Filter by app id, slug, or name").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action(async (opts) => {
-    const mode = resolveOutputMode(opts.json);
-    try {
-      const topolo = await buildClient();
-      if (!topolo) {
-        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
-      }
-      const rows = await topolo.client.listActions({ service: opts.service });
-      emit({ actions: rows }, mode, () => formatActionRows(rows));
-    } catch (err) {
-      fail(err, mode);
-    }
-  });
-  actions.command("get <action>").description("Describe one Topolo action by action id, name, or tool name").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (action, opts) => {
-    const mode = resolveOutputMode(opts.json);
-    try {
-      const topolo = await buildClient();
-      if (!topolo) {
-        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
-      }
-      const entry = await topolo.client.getAction(action);
-      emit(entry, mode, () => formatActionDetail(entry));
-    } catch (err) {
-      fail(err, mode);
-    }
-  });
-  actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json>", "JSON action input", "{}").option("--confirm", "Acknowledge a mutating action").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (action, opts) => {
-    const mode = resolveOutputMode(opts.json);
-    try {
-      const topolo = await buildClient();
-      if (!topolo) {
-        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
-      }
-      const input2 = parseJsonObject(opts.data || "{}");
-      const result = await topolo.client.callAction(action, input2, { confirm: opts.confirm === true });
-      emit(result, mode, () => JSON.stringify(result, null, 2));
-    } catch (err) {
-      fail(err, mode);
-    }
-  });
-}
-function parseJsonObject(value) {
-  let parsed;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw new Error("--data must be valid JSON");
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("--data must be a JSON object");
-  }
-  return parsed;
-}
-function formatActionRows(rows) {
-  if (rows.length === 0) return "No actions available for this credential.";
-  const serviceWidth = Math.max(7, ...rows.map((row) => (row.appSlug || row.appId).length));
-  const nameWidth = Math.max(6, ...rows.map((row) => row.name.length));
-  const methodWidth = Math.max(6, ...rows.map((row) => row.method.length));
-  const lines = [
-    `${"SERVICE".padEnd(serviceWidth)}  ${"ACTION".padEnd(nameWidth)}  ${"METHOD".padEnd(methodWidth)}  CONFIRM  PERMISSION`,
-    `${"-".repeat(serviceWidth)}  ${"-".repeat(nameWidth)}  ${"-".repeat(methodWidth)}  -------  ----------`
-  ];
-  for (const row of rows) {
-    const confirmation = row.requiresConfirmation ? "yes" : "no";
-    lines.push(
-      `${(row.appSlug || row.appId).padEnd(serviceWidth)}  ${row.name.padEnd(nameWidth)}  ${row.method.padEnd(methodWidth)}  ${confirmation.padEnd(7)}  ${row.requiredPermission}`
-    );
-  }
-  return lines.join("\n");
-}
-function formatActionDetail(action) {
-  return [
-    `Action:       ${action.name}`,
-    `ID:           ${action.actionId}`,
-    `Tool:         ${action.toolName || "-"}`,
-    `Service:      ${action.appSlug || action.appId}`,
-    `Method:       ${action.method}`,
-    `Path:         ${action.path}`,
-    `Permission:   ${action.requiredPermission}`,
-    `Confirmation: ${action.requiresConfirmation ? "required" : "not required"}`,
-    "",
-    action.description
-  ].join("\n");
-}
-
 // src/commands/api.ts
 var STATIC_APP_IDS = new Set(Object.keys(DEFAULT_APP_URLS));
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
@@ -3832,6 +3975,113 @@ function parseQueryPairs(pairs) {
   return out;
 }
 
+// src/commands/actions.ts
+function registerActionsCommand(program2) {
+  const actions = program2.command("actions").description("Search permission-scoped Topolo actions for one application").option("-s, --service <service>", "App id, slug, or name (required for search)").option("-q, --query <query>", "Filter by action id, name, or title").option("--cursor <cursor>", "Continuation cursor from the previous page").option("--limit <limit>", "Page size (1-100)", "25").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      if (!opts.service?.trim()) throw new Error("--service is required for action search");
+      const result = await topolo.client.searchActions({
+        service: opts.service.trim(),
+        query: opts.query,
+        cursor: opts.cursor,
+        limit: parsePageSize(opts.limit)
+      });
+      emit(result, mode, () => formatActionRows(result.actions, result.page.nextCursor));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("get <action>").description("Describe one Topolo action by exact action id").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      const entry = await topolo.client.getAction(action);
+      emit(entry, mode, () => formatActionDetail(entry));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json>", "JSON action input", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Acknowledge a mutating action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      const input2 = parseJsonObject(opts.data || "{}");
+      const resource = parseResourceOption(opts.resourceType, opts.resourceId);
+      const result = await topolo.client.callAction(action, input2, {
+        confirm: opts.confirm === true,
+        ...resource ? { resource } : {}
+      });
+      emit(result, mode, () => JSON.stringify(result, null, 2));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function parseJsonObject(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("--data must be valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--data must be a JSON object");
+  }
+  return parsed;
+}
+function formatActionRows(rows, nextCursor = null) {
+  if (rows.length === 0) return "No actions available for this credential.";
+  const serviceWidth = Math.max(7, ...rows.map((row) => (row.appSlug || row.appId).length));
+  const nameWidth = Math.max(6, ...rows.map((row) => row.name.length));
+  const methodWidth = Math.max(6, ...rows.map((row) => row.method.length));
+  const lines = [
+    `${"SERVICE".padEnd(serviceWidth)}  ${"ACTION".padEnd(nameWidth)}  ${"METHOD".padEnd(methodWidth)}  CONFIRM  PERMISSION`,
+    `${"-".repeat(serviceWidth)}  ${"-".repeat(nameWidth)}  ${"-".repeat(methodWidth)}  -------  ----------`
+  ];
+  for (const row of rows) {
+    const confirmation = row.requiresConfirmation ? "yes" : "no";
+    lines.push(
+      `${(row.appSlug || row.appId).padEnd(serviceWidth)}  ${row.name.padEnd(nameWidth)}  ${row.method.padEnd(methodWidth)}  ${confirmation.padEnd(7)}  ${row.requiredPermission}`
+    );
+  }
+  if (nextCursor) lines.push("", `Next cursor: ${nextCursor}`);
+  return lines.join("\n");
+}
+function parsePageSize(value) {
+  const parsed = Number.parseInt(value || "25", 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 100) {
+    throw new Error("--limit must be an integer between 1 and 100");
+  }
+  return parsed;
+}
+function formatActionDetail(action) {
+  return [
+    `Action:       ${action.name}`,
+    `ID:           ${action.actionId}`,
+    `Tool:         ${action.toolName || "-"}`,
+    `Service:      ${action.appSlug || action.appId}`,
+    `Target:       ${action.target || "-"}`,
+    `API URL:      ${action.apiBaseUrl || "-"}`,
+    `Method:       ${action.method}`,
+    `Path:         ${action.path}`,
+    `Permission:   ${action.requiredPermission}`,
+    `Confirmation: ${action.requiresConfirmation ? "required" : "not required"}`,
+    "",
+    action.description
+  ].join("\n");
+}
+
 // src/commands/apps.ts
 import { execSync } from "child_process";
 import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
@@ -5120,7 +5370,7 @@ function packageJson(application, target, options) {
       dependencies["@topolo/sdk"] = topoloPackageVersion("@topolo/sdk", target);
       scripts.deploy = "npm run build && wrangler deploy";
     }
-    devDependencies.wrangler = "^4.40.2";
+    devDependencies.wrangler = "^4.91.0";
   }
   if (target === "platform" && hasScaffoldResources(options.resources)) {
     scripts["check:deploy-config"] = "wrangler deploy --config apps/api/wrangler.toml --env staging --dry-run --outdir .wrangler/api-build && wrangler deploy --config apps/web/wrangler.toml --env staging --dry-run --outdir .wrangler/web-build";
@@ -5140,11 +5390,11 @@ function topoloPackageVersion(packageName, target) {
   if (target === "developer") {
     if (packageName === "@topolo/login") return "^0.1.0";
     if (packageName === "@topolo-io/auth-client") return "^1.0.0";
-    if (packageName === "@topolo/sdk") return "^0.4.9";
+    if (packageName === "@topolo/sdk") return "^0.8.1";
     return "^0.1.0";
   }
   const platformPackageVersions = {
-    "@topolo/sdk": "^0.4.9",
+    "@topolo/sdk": "^0.8.1",
     "@topolo/login": "^0.1.0",
     "@topolo-io/app-funnel": "^0.1.6",
     "@topolo-io/app-launcher": "^0.1.15",
@@ -8372,15 +8622,20 @@ var CLOUDCONTROL_LOCAL_APPLICATION = {
   deployTargets: []
 };
 function registerAppsCommand(program2) {
-  const apps = program2.command("apps").description("List Topolo platform applications available to the current credential").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action(async (opts) => {
+  const apps = program2.command("apps").description("Search Topolo platform applications available to the current credential").option("-q, --query <query>", "Filter by app id, slug, or name").option("--cursor <cursor>", "Continuation cursor from the previous page").option("--limit <limit>", "Page size (1-100)", "25").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
       const topolo = await buildClient();
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
       }
-      const rows = applicationRowsFromCatalog(await topolo.client.listServices());
-      emit({ applications: rows }, mode, () => formatRows(rows));
+      const result = await topolo.client.searchServices({
+        query: opts.query,
+        cursor: opts.cursor,
+        limit: parsePageSize2(opts.limit)
+      });
+      const rows = applicationRowsFromCatalog(result.services);
+      emit({ applications: rows, page: result.page }, mode, () => formatRows(rows));
     } catch (err) {
       fail(err, mode);
     }
@@ -8392,7 +8647,8 @@ function registerAppsCommand(program2) {
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
       }
-      const app = resolveCatalogApplication(await topolo.client.listServices(), application);
+      const entry = await topolo.client.getService(application);
+      const app = applicationRowsFromCatalog([entry])[0];
       emit({ application: app }, mode, () => formatApplicationRow(app));
     } catch (err) {
       fail(err, mode);
@@ -8512,16 +8768,12 @@ function applicationRowsFromCatalog(catalog) {
     deployTargets: 0
   })).sort((left, right) => left.id.localeCompare(right.id));
 }
-function resolveCatalogApplication(catalog, application) {
-  const needle = application.trim().toLowerCase();
-  const rows = applicationRowsFromCatalog(catalog);
-  const match = rows.find(
-    (row) => row.id.toLowerCase() === needle || row.name.toLowerCase() === needle || row.services.some((service) => service.toLowerCase() === needle)
-  );
-  if (!match) {
-    throw new Error(`Unknown application "${application}". Run \`topolo apps --json\` to discover applications available to this credential.`);
+function parsePageSize2(value) {
+  const parsed = Number.parseInt(value || "25", 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 100) {
+    throw new Error("--limit must be an integer between 1 and 100");
   }
-  return match;
+  return parsed;
 }
 function resolveApplication(application) {
   const id = application.trim().toLowerCase();
@@ -9074,7 +9326,7 @@ async function requirePlatformAdminSession() {
 
 // 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(async (opts) => {
+  program2.command("services").description("Search Topolo services the SDK can route to").option("-q, --query <query>", "Filter by app id, slug, or name").option("--cursor <cursor>", "Continuation cursor from the previous page").option("--limit <limit>", "Page size (1-100)", "25").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
       const environment = selectedEnvironment();
@@ -9083,8 +9335,13 @@ function registerServicesCommand(program2) {
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
       }
-      const rows = buildRows(await topolo.client.listServices(), config.serviceUrls, environment);
-      emit({ environment, services: rows }, mode, () => formatRows2(rows, environment));
+      const result = await topolo.client.searchServices({
+        query: opts.query,
+        cursor: opts.cursor,
+        limit: parsePageSize3(opts.limit)
+      });
+      const rows = buildRows(result.services, config.serviceUrls, environment);
+      emit({ environment, services: rows, page: result.page }, mode, () => formatRows2(rows, environment, result.page.nextCursor));
     } catch (err) {
       fail(err, mode);
     }
@@ -9111,7 +9368,7 @@ function buildRows(catalog, overrides, environment = selectedEnvironment()) {
     };
   }).sort((left, right) => left.id.localeCompare(right.id));
 }
-function formatRows2(rows, environment = selectedEnvironment()) {
+function formatRows2(rows, environment = selectedEnvironment(), nextCursor = null) {
   const idWidth = Math.max(3, ...rows.map((r) => r.id.length));
   const urlWidth = Math.max(7, ...rows.map((r) => (r.effectiveUrl ?? "-").length));
   const lines = [];
@@ -9126,8 +9383,14 @@ function formatRows2(rows, environment = selectedEnvironment()) {
       `${r.id.padEnd(idWidth)}  ${effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : "".padEnd(8)}  ${r.environmentSafe ? "yes" : "no"}    ${apiKeyResource}`
     );
   }
+  if (nextCursor) lines.push("", `Next cursor: ${nextCursor}`);
   return lines.join("\n");
 }
+function parsePageSize3(value) {
+  const parsed = Number.parseInt(value || "25", 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 100) throw new Error("--limit must be an integer between 1 and 100");
+  return parsed;
+}
 function isStagingUrl(value) {
   const url = value.toLowerCase();
   return url.includes(".stg.topolo.us") || url.includes("localhost") || url.includes("127.0.0.1") || url.includes("topolo-staging");
@@ -9900,6 +10163,167 @@ function formatStatus(rows) {
   ).join("\n");
 }
 
+// src/commands/context.ts
+function makeClient(credential, serviceUrls) {
+  return createTopolo({
+    credential,
+    agent: { clientName: "topolo-cli", clientVersion: CLI_VERSION },
+    serviceUrls
+  });
+}
+function unwrap(res) {
+  const r = res ?? {};
+  return r.data ?? r;
+}
+async function fetchMe(credential, serviceUrls) {
+  const topolo = makeClient(credential, serviceUrls);
+  const data = unwrap(await topolo.client.request({ service: "auth", method: "GET", path: "/api/auth/me" }));
+  const user = data.user ?? {};
+  const rawMemberships = user.organizationMemberships || data.organizations || [];
+  const memberships = rawMemberships.filter((m) => m && m.id);
+  const activeType = user.orgId ? "organization" : "personal";
+  return { memberships, activeType, activeOrgId: user.orgId || void 0 };
+}
+function credentialFromTokens(tokens) {
+  const accessToken = tokens.accessToken || tokens.access_token;
+  const refreshToken = tokens.refreshToken || tokens.refresh_token;
+  const expiresIn = tokens.expiresIn || tokens.expires_in;
+  const expiresAtRaw = tokens.expiresAt || tokens.expires_at;
+  return {
+    kind: "access_token",
+    accessToken,
+    ...refreshToken ? { refreshToken } : {},
+    ...expiresAtRaw ? { expiresAt: expiresAtRaw } : expiresIn ? { expiresAt: Math.floor(Date.now() / 1e3) + expiresIn } : {}
+  };
+}
+async function exchangeForContext(credential, serviceUrls, target) {
+  const topolo = makeClient(credential, serviceUrls);
+  const data = unwrap(
+    await topolo.client.request({
+      service: "auth",
+      method: "PUT",
+      path: "/api/me/active-context",
+      body: {
+        contextType: target.type,
+        contextId: target.type === "organization" ? target.id : null
+      },
+      confirm: true
+    })
+  );
+  const tokens = data.tokens || {};
+  return credentialFromTokens(tokens);
+}
+function labelFor(ctx) {
+  if (ctx.contextType === "personal") return "Personal";
+  return ctx.organizationName || ctx.organizationSlug || ctx.organizationId || "organization";
+}
+function registerContextCommand(program2) {
+  const context = program2.command("context").description("Show and switch the active context (personal or an organization)");
+  context.command("ls", { isDefault: true }).alias("list").description("List the contexts you can act in and which is active").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const environment = selectedEnvironment();
+      const config = await readConfig();
+      const profile = profileForEnvironment(config, environment);
+      const stored = profile.contexts ?? {};
+      const activeKey = profile.activeContext;
+      const rows = /* @__PURE__ */ new Map();
+      for (const [key, ctx] of Object.entries(stored)) {
+        rows.set(key, { key, type: ctx.contextType, label: labelFor(ctx), signedIn: true, active: key === activeKey });
+      }
+      const cred = await refreshCredentialIfNeeded(environment);
+      if (cred) {
+        try {
+          const me = await fetchMe(cred, resolvedProfileConfig(config, environment).serviceUrls);
+          const personalKey = contextKey("personal");
+          if (!rows.has(personalKey)) {
+            rows.set(personalKey, { key: personalKey, type: "personal", label: "Personal", signedIn: false, active: personalKey === activeKey });
+          }
+          for (const m of me.memberships) {
+            const key = contextKey("organization", m.id);
+            if (!rows.has(key)) {
+              rows.set(key, { key, type: "organization", label: m.name || m.slug || m.id, signedIn: false, active: key === activeKey });
+            }
+          }
+        } catch {
+        }
+      }
+      const list = [...rows.values()];
+      emit({ environment, active: activeKey ?? null, contexts: list }, mode, () => {
+        if (list.length === 0) return "No contexts yet. Run `topolo auth login` first.";
+        const lines = [`Contexts (${environmentLabel(environment)}):`, ""];
+        for (const r of list) {
+          const marks = [r.active ? "active" : "", r.signedIn ? "signed in" : "available"].filter(Boolean).join(", ");
+          lines.push(`  ${r.active ? "*" : " "} ${r.label}  (${r.type})  [${marks}]`);
+        }
+        lines.push("", "Switch with: topolo context use <organization|personal>");
+        return lines.join("\n");
+      });
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  context.command("use <target>").description('Switch the active context (an organization name/slug, or "personal")').option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (target, opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const environment = selectedEnvironment();
+      const config = await readConfig();
+      const profile = profileForEnvironment(config, environment);
+      const serviceUrls = resolvedProfileConfig(config, environment).serviceUrls;
+      const cred = await refreshCredentialIfNeeded(environment);
+      if (!cred) {
+        throw new Error("Not signed in. Run `topolo auth login` first.");
+      }
+      const wantPersonal = /^(personal|me)$/i.test(target.trim());
+      let resolved;
+      if (wantPersonal) {
+        resolved = { contextType: "personal" };
+      } else {
+        const me = await fetchMe(cred, serviceUrls);
+        const needle = target.trim().toLowerCase();
+        const match = me.memberships.find(
+          (m) => m.id === target || m.slug?.toLowerCase() === needle || m.name?.toLowerCase() === needle
+        );
+        if (!match) {
+          const names = me.memberships.map((m) => m.slug || m.name || m.id);
+          throw new Error(
+            `You are not a member of "${target}". Available: personal${names.length ? ", " + names.join(", ") : ""}.`
+          );
+        }
+        resolved = {
+          contextType: "organization",
+          organizationId: match.id,
+          organizationSlug: match.slug,
+          organizationName: match.name
+        };
+      }
+      const key = contextKey(resolved.contextType, resolved.organizationId);
+      const existing = profile.contexts?.[key];
+      let updated = config;
+      if (existing?.credential) {
+        updated = activateContext(config, environment, key);
+      } else {
+        const newCredential = await exchangeForContext(cred, serviceUrls, {
+          type: resolved.contextType,
+          id: resolved.organizationId
+        });
+        resolved.credential = newCredential;
+        resolved.oauthClientId = existing?.oauthClientId ?? profile.oauthClientId;
+        updated = writeContextCredential(config, environment, resolved, true);
+      }
+      await writeConfig(updated);
+      emit(
+        { environment, active: key, context: { type: resolved.contextType, label: labelFor(resolved) } },
+        mode,
+        () => `
+  \u2713 Now acting as ${labelFor(resolved)} (${resolved.contextType}).`
+      );
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+
 // src/index.ts
 var program = new Command();
 var argv;
@@ -9929,6 +10353,7 @@ registerPlatformCommand(program);
 registerServicesCommand(program);
 registerSeedCommands(program);
 registerSkillsCommand(program);
+registerContextCommand(program);
 program.parseAsync(argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);