zinkee 0.1.53 → 0.1.55

package/dist/index.js

@@ -16,8 +16,9 @@ import {
   normalizeSchemaFieldCreatePayload,
   normalizeSchemaFieldType,
   normalizeSchemaFieldUpdatePayload,
-  printTable
-} from "./chunk-IEW5RTJV.js";
+  printTable,
+  toCliError
+} from "./chunk-FIWBICYE.js";
 
 // src/cli-runner.ts
 import { realpathSync } from "fs";
@@ -29,6 +30,7 @@ var HOISTABLE_GLOBAL_FLAGS = {
   "--profile": "value",
   "--base-url": "value",
   "--api-key": "value",
+  "--workspace": "value",
   "--read-only": "boolean",
   "--json": "boolean"
 };
@@ -250,7 +252,7 @@ ${list}`
   };
 }
 async function showExamples(commandName, json, stdout, filters = {}) {
-  const { getCommandExamples } = await import("./examples-SKT3O7KD.js");
+  const { getCommandExamples } = await import("./examples-UJZKITVW.js");
   const examples = getCommandExamples(commandName, filters);
   if (examples.length === 0) {
     throw new CliError("invalid_cli_usage", `No examples registered for "${commandName}".`);
@@ -290,7 +292,7 @@ import { createRequire } from "module";
 import { Command as Command4 } from "commander";
 
 // src/config.ts
-import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
 import { parseTOML, stringifyTOML } from "confbox/toml";
@@ -299,7 +301,22 @@ var redactedSecretMask = "********";
 var ENV_API_KEY = "ZINKEE_API_KEY";
 var ENV_BASE_URL = "ZINKEE_API_BASE_URL";
 var ENV_PROFILE = "ZINKEE_PROFILE";
+var ENV_WORKSPACE = "ZINKEE_WORKSPACE";
 var DEFAULT_PRODUCTION_BASE_URL = "https://api-z2.zinkee.com";
+var DEFAULT_PRODUCTION_BACKEND_URL = "https://backend-z2.zinkee.com";
+var SESSION_PROFILE_TYPE = "session";
+var DEFAULT_SESSION_PROFILE = "superadmin";
+var profileKeysByTomlKey = /* @__PURE__ */ new Map([
+  ["type", "type"],
+  ["api_key", "apiKey"],
+  ["base_url", "baseUrl"],
+  ["backend_url", "backendUrl"],
+  ["email", "email"],
+  ["session_token", "sessionToken"]
+]);
+var tomlKeysByProfileKey = new Map(
+  [...profileKeysByTomlKey].map(([tomlKey, profileKey]) => [profileKey, tomlKey])
+);
 var ProfileResolutionError = class extends Error {
   name = "ProfileResolutionError";
   constructor(message) {
@@ -322,12 +339,9 @@ function parseProfileConfig(value) {
     return profile;
   }
   for (const [key, rawValue] of Object.entries(value)) {
-    if (key === "api_key") {
-      profile.apiKey = toStringValue(rawValue);
-      continue;
-    }
-    if (key === "base_url") {
-      profile.baseUrl = toStringValue(rawValue);
+    const profileKey = profileKeysByTomlKey.get(key);
+    if (profileKey) {
+      profile[profileKey] = toStringValue(rawValue);
       continue;
     }
     profile[key] = rawValue;
@@ -380,15 +394,7 @@ function serializeProfileConfig(profile) {
     if (value === void 0) {
       continue;
     }
-    if (key === "apiKey") {
-      serialized.api_key = value;
-      continue;
-    }
-    if (key === "baseUrl") {
-      serialized.base_url = value;
-      continue;
-    }
-    serialized[key] = value;
+    serialized[tomlKeysByProfileKey.get(key) ?? key] = value;
   }
   return serialized;
 }
@@ -413,7 +419,8 @@ function serializeConfig(config) {
 }
 function writeConfig(config, filePath = defaultConfigPath) {
   mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, serializeConfig(config), "utf8");
+  writeFileSync(filePath, serializeConfig(config), { encoding: "utf8", mode: 384 });
+  chmodSync(filePath, 384);
 }
 function setProfileConfig(config, profileName, updates) {
   return {
@@ -454,9 +461,19 @@ function redactSecret(value) {
 function redactProfile(profile) {
   return {
     ...profile,
-    apiKey: redactSecret(profile.apiKey)
+    apiKey: redactSecret(profile.apiKey),
+    sessionToken: redactSecret(profile.sessionToken)
   };
 }
+function isSessionProfile(profile) {
+  return profile?.type === SESSION_PROFILE_TYPE;
+}
+function describeProfileCredential(redactedProfile) {
+  if (isSessionProfile(redactedProfile)) {
+    return redactedProfile.email ? `session ${redactedProfile.email}` : "session";
+  }
+  return redactedProfile.apiKey ?? "";
+}
 function redactConfig(config) {
   return {
     ...config,
@@ -507,6 +524,9 @@ function readEnvBaseUrl(env = process.env) {
 function readEnvProfile(env = process.env) {
   return toNonEmptyString(env[ENV_PROFILE]);
 }
+function readEnvWorkspace(env = process.env) {
+  return toNonEmptyString(env[ENV_WORKSPACE]);
+}
 
 // src/commands/shared.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -531,7 +551,196 @@ function normalizeUuidOrSlug(input) {
   };
 }
 
+// src/session.ts
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var MAX_WORKSPACE_SUGGESTIONS = 5;
+var WORKSPACES_LIST_ACTION = "Run `zinkee workspaces list` to see the available workspaces.";
+function decodeTokenExpiry(token) {
+  const payload = token.split(".")[1];
+  if (!payload) {
+    return void 0;
+  }
+  try {
+    const { exp } = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return typeof exp === "number" ? new Date(exp * 1e3) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isTokenExpired(token, now = Date.now()) {
+  const expiry = decodeTokenExpiry(token);
+  return expiry !== void 0 && expiry.getTime() <= now;
+}
+function sessionRequiredError(profile) {
+  const action = `Run \`zinkee login --profile ${profile}\`.`;
+  return new CliError(
+    "authentication_required",
+    `Session for profile "${profile}" has expired or is missing. ${action}`,
+    { profile, action }
+  );
+}
+function requireSession(profile) {
+  const token = profile.sessionToken;
+  if (!token || isTokenExpired(token)) {
+    throw sessionRequiredError(profile.name);
+  }
+  return {
+    profile: profile.name,
+    backendUrl: profile.backendUrl ?? DEFAULT_PRODUCTION_BACKEND_URL,
+    token
+  };
+}
+function isHttpStatus(error, status) {
+  return error instanceof ApiClientError && error.status === status;
+}
+async function callBackend(session, call) {
+  try {
+    return await call(new ApiClient({ baseUrl: session.backendUrl, apiKey: session.token }));
+  } catch (error) {
+    if (isHttpStatus(error, 401)) {
+      throw sessionRequiredError(session.profile);
+    }
+    throw error;
+  }
+}
+async function signIn(backendUrl, email, password) {
+  let response;
+  try {
+    response = await new ApiClient({ baseUrl: backendUrl }).requestJson("/member/sign-in", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email, password })
+    });
+  } catch (error) {
+    if (isHttpStatus(error, 401)) {
+      throw new CliError(
+        "authentication_required",
+        "Sign-in failed: invalid email or password.",
+        toCliError(error).details
+      );
+    }
+    throw error;
+  }
+  if (typeof response?.token !== "string" || response.token.length === 0) {
+    throw new CliError("invalid_json", "Sign-in response did not include a session token.");
+  }
+  return response.token;
+}
+async function listWorkspaces(session) {
+  const organizations = await callBackend(
+    session,
+    (client) => client.getJson("/org/list")
+  );
+  return (organizations ?? []).flatMap(
+    (organization) => (organization.workspaces ?? []).map((workspace) => ({
+      organizationId: organization.id,
+      organizationName: organization.name,
+      workspaceId: workspace.id,
+      workspaceName: workspace.name,
+      publicName: workspace.publicName ?? void 0,
+      active: workspace.active !== false
+    }))
+  );
+}
+function issueWorkspaceToken(session, workspaceName) {
+  return callBackend(session, async (client) => {
+    const response = await client.requestJson(
+      `/${encodeURIComponent(workspaceName)}/settings/cli/runtime-token`,
+      { method: "POST" }
+    );
+    if (typeof response?.token !== "string" || response.token.length === 0) {
+      throw new CliError(
+        "invalid_json",
+        `Workspace token response for "${workspaceName}" did not include a token.`
+      );
+    }
+    return { ...response, token: response.token, workspaceName: response.workspaceName ?? workspaceName };
+  });
+}
+function requireActive(workspace, requested) {
+  if (!workspace.active) {
+    throw new CliError(
+      "configuration_error",
+      `Workspace "${workspace.workspaceName}" is inactive.`,
+      { workspace: requested, workspaceId: workspace.workspaceId }
+    );
+  }
+  return workspace;
+}
+function findWorkspaceById(workspaces, id) {
+  const match = workspaces.find((workspace) => workspace.workspaceId.toLowerCase() === id.toLowerCase());
+  if (!match) {
+    throw new CliError("configuration_error", `Workspace "${id}" not found.`, {
+      workspace: id,
+      action: WORKSPACES_LIST_ACTION
+    });
+  }
+  return requireActive(match, id);
+}
+function findWorkspaceByName(workspaces, name) {
+  const needle = name.toLowerCase();
+  const names = (workspace) => [workspace.workspaceName, workspace.publicName].filter((value) => Boolean(value));
+  const candidates = workspaces.filter(
+    (workspace) => names(workspace).some((value) => value.toLowerCase() === needle)
+  );
+  if (candidates.length === 0) {
+    const suggestions = [
+      ...new Set(
+        workspaces.filter((workspace) => names(workspace).some((value) => value.toLowerCase().includes(needle))).map((workspace) => workspace.workspaceName)
+      )
+    ].slice(0, MAX_WORKSPACE_SUGGESTIONS);
+    const hint = suggestions.length > 0 ? ` Did you mean ${suggestions.map((value) => `"${value}"`).join(", ")}?` : "";
+    throw new CliError("configuration_error", `Workspace "${name}" not found.${hint}`, {
+      workspace: name,
+      ...suggestions.length > 0 ? { suggestions } : {},
+      action: WORKSPACES_LIST_ACTION
+    });
+  }
+  const exact = candidates.find((workspace) => workspace.workspaceName === name);
+  if (exact) {
+    return requireActive(exact, name);
+  }
+  const active = candidates.filter((workspace) => workspace.active);
+  if (active.length === 1) {
+    return active[0];
+  }
+  if (active.length === 0) {
+    return requireActive(candidates[0], name);
+  }
+  const matches = active.map((workspace) => workspace.workspaceName);
+  throw new CliError(
+    "configuration_error",
+    `Workspace "${name}" matches several workspaces: ${matches.map((value) => `"${value}"`).join(", ")}. Pass the exact name or the workspace id.`,
+    { workspace: name, candidates: matches }
+  );
+}
+async function exchangeWorkspaceToken(session, workspace) {
+  const requested = workspace.trim();
+  if (UUID_PATTERN.test(requested)) {
+    const match = findWorkspaceById(await listWorkspaces(session), requested);
+    return issueWorkspaceToken(session, match.workspaceName);
+  }
+  try {
+    return await issueWorkspaceToken(session, requested);
+  } catch (error) {
+    if (!isHttpStatus(error, 410)) {
+      throw error;
+    }
+    const match = findWorkspaceByName(await listWorkspaces(session), requested);
+    if (match.workspaceName === requested) {
+      throw error;
+    }
+    return issueWorkspaceToken(session, match.workspaceName);
+  }
+}
+function createWorkspaceTokenProvider(session, workspace) {
+  return async () => (await exchangeWorkspaceToken(session, workspace)).token;
+}
+
 // src/runtime-context.ts
+function workspaceNeedsSession(source) {
+  return `${source} only works with a session profile (run \`zinkee login\`).`;
+}
 function resolveRuntimeContext(config, overrides = {}) {
   const envProfile = readEnvProfile();
   const envApiKey = readEnvApiKey();
@@ -540,6 +749,8 @@ function resolveRuntimeContext(config, overrides = {}) {
   const profileOverride = overrides.profile ?? envProfile;
   const apiKeyOverride = overrides.apiKey ?? envApiKey;
   const baseUrlOverride = flagBaseUrl ?? envBaseUrl;
+  const selectedProfileName = profileOverride ?? config.defaultProfile;
+  const selectsSessionProfile = selectedProfileName !== void 0 && isSessionProfile(config.profiles[selectedProfileName]);
   if (apiKeyOverride && !baseUrlOverride) {
     throw new ProfileResolutionError(
       `Runtime API key was provided, but ${ENV_BASE_URL} or --base-url is missing.`
@@ -547,10 +758,15 @@ function resolveRuntimeContext(config, overrides = {}) {
   }
   if (baseUrlOverride && !apiKeyOverride) {
     throw new ProfileResolutionError(
-      `Runtime base URL was provided, but ${ENV_API_KEY} or --api-key is missing.`
+      selectsSessionProfile ? `Session profile "${selectedProfileName}" takes its URLs from \`zinkee login\`: drop ${ENV_BASE_URL} or --base-url, or log in again with --backend-url and --base-url.` : `Runtime base URL was provided, but ${ENV_API_KEY} or --api-key is missing.`
     );
   }
   if (apiKeyOverride && baseUrlOverride) {
+    if (overrides.workspace !== void 0) {
+      throw new ProfileResolutionError(
+        `${workspaceNeedsSession("--workspace")} It cannot be combined with a runtime API key.`
+      );
+    }
     return {
       profile: profileOverride ?? "runtime",
       baseUrl: baseUrlOverride,
@@ -564,10 +780,31 @@ function resolveRuntimeContext(config, overrides = {}) {
     baseUrl: baseUrlOverride,
     apiKey: apiKeyOverride
   });
+  const flagWorkspace = overrides.workspace?.trim() || void 0;
+  const workspace = flagWorkspace ?? readEnvWorkspace();
+  if (!isSessionProfile(profile)) {
+    if (workspace) {
+      throw new ProfileResolutionError(workspaceNeedsSession(flagWorkspace ? "--workspace" : ENV_WORKSPACE));
+    }
+    return {
+      profile: profile.name,
+      baseUrl: baseUrlOverride ?? profile.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL,
+      apiKey: apiKeyOverride ?? profile.apiKey,
+      readOnly: overrides.readOnly ?? false,
+      json: overrides.json ?? false
+    };
+  }
+  if (!workspace) {
+    throw new ProfileResolutionError(
+      `Profile "${profile.name}" is a session profile: pass --workspace <name> or set ${ENV_WORKSPACE}.`
+    );
+  }
+  const { backendUrl, token } = requireSession(profile);
   return {
     profile: profile.name,
-    baseUrl: baseUrlOverride ?? profile.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL,
-    apiKey: apiKeyOverride ?? profile.apiKey,
+    baseUrl: profile.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL,
+    workspace,
+    session: { backendUrl, token },
     readOnly: overrides.readOnly ?? false,
     json: overrides.json ?? false
   };
@@ -584,8 +821,9 @@ function createCommandContext(command, filePath) {
         `Resolved profile "${runtime.profile}" is missing a base URL.`
       );
     }
+    const getToken = runtime.session && runtime.workspace ? createWorkspaceTokenProvider({ profile: runtime.profile, ...runtime.session }, runtime.workspace) : void 0;
     return {
-      client: new ApiClient({ baseUrl: runtime.baseUrl, apiKey: runtime.apiKey }),
+      client: new ApiClient({ baseUrl: runtime.baseUrl, apiKey: runtime.apiKey, getToken }),
       json: runtime.json,
       profile: runtime.profile,
       readOnly: runtime.readOnly
@@ -746,9 +984,9 @@ function registerConfigCommands(program, options = {}) {
           name,
           default: data.defaultProfile === name ? "yes" : "",
           baseUrl: typeof profile.baseUrl === "string" ? profile.baseUrl : "",
-          apiKey: typeof profile.apiKey === "string" ? profile.apiKey : ""
+          credential: describeProfileCredential(profile)
         })),
-        ["name", "default", "baseUrl", "apiKey"],
+        ["name", "default", "baseUrl", "credential"],
         stdout
       );
     } catch (error) {
@@ -3592,6 +3830,9 @@ async function downloadToOutput(download, stdout, outputPath) {
     await rename(tempFile, outputPath);
     return bytes;
   } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
     const cause = error instanceof ApiClientError ? error.cause : error;
     const isFileError = cause instanceof Error && "syscall" in cause && ["open", "write", "writev", "close"].includes(String(cause.syscall));
     if (error instanceof ApiClientError && !isFileError) {
@@ -4351,9 +4592,9 @@ function emitProfilesTable(stdout, data) {
       name: profile.name,
       default: profile.isDefault ? "yes" : "",
       baseUrl: profile.baseUrl ?? "",
-      apiKey: profile.apiKey ?? ""
+      credential: describeProfileCredential(profile)
     })),
-    ["name", "default", "baseUrl", "apiKey"],
+    ["name", "default", "baseUrl", "credential"],
     stdout
   );
 }
@@ -4433,7 +4674,13 @@ function registerProfilesCommands(program, options = {}) {
       );
     }
     const config = readRequiredConfig(filePath);
-    getRequiredProfile(config, profileName);
+    const profile = getRequiredProfile(config, profileName);
+    if (isSessionProfile(profile)) {
+      throw new CliError(
+        "configuration_error",
+        `Profile "${profileName}" is a session profile. Run \`zinkee login --profile ${profileName}\` to renew its session, adding --backend-url and --base-url to change its environment.`
+      );
+    }
     const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
     const nextConfig = setProfileConfig(config, profileName, {
       apiKey: commandOptions.apiKey,
@@ -5459,6 +5706,213 @@ function registerSchemasCommands(program, options = {}) {
   });
 }
 
+// src/commands/session.ts
+import { createInterface } from "readline/promises";
+import { Writable as Writable2 } from "stream";
+function readConfigOrEmpty(filePath) {
+  try {
+    return readConfigIfExists(filePath) ?? { profiles: {} };
+  } catch (error) {
+    toConfigurationError(filePath, error);
+  }
+}
+function normalizeUrl(value, source) {
+  try {
+    return validateBaseUrl(value, source);
+  } catch (error) {
+    throw new CliError("configuration_error", error instanceof Error ? error.message : String(error));
+  }
+}
+function resolveLoginUrls(options, existing) {
+  const backendFlag = options.backendUrl === void 0 ? void 0 : normalizeUrl(options.backendUrl, '"--backend-url"');
+  const baseFlag = options.baseUrl === void 0 ? void 0 : normalizeUrl(options.baseUrl, '"--base-url"');
+  if (backendFlag === void 0 && baseFlag === void 0) {
+    return {
+      backendUrl: existing?.backendUrl ?? DEFAULT_PRODUCTION_BACKEND_URL,
+      baseUrl: existing?.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL
+    };
+  }
+  if (backendFlag === void 0 || baseFlag === void 0) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Pass both "--backend-url" and "--base-url": a session only works with the Public API of the same environment.'
+    );
+  }
+  return { backendUrl: backendFlag, baseUrl: baseFlag };
+}
+async function prompt(input, label, hidden) {
+  const output = new Writable2({
+    write(chunk, _encoding, callback) {
+      if (!hidden) {
+        process.stderr.write(chunk);
+      }
+      callback();
+    }
+  });
+  const rl = createInterface({ input, output, terminal: true, historySize: 0 });
+  const controller = new AbortController();
+  rl.on("SIGINT", () => controller.abort());
+  rl.on("close", () => controller.abort());
+  if (hidden) {
+    process.stderr.write(label);
+  }
+  try {
+    return await rl.question(hidden ? "" : label, { signal: controller.signal });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new CliError("invalid_cli_usage", "Login cancelled.", {}, 130);
+    }
+    throw error;
+  } finally {
+    if (hidden) {
+      process.stderr.write("\n");
+    }
+    rl.close();
+  }
+}
+async function readAll(input) {
+  const chunks = [];
+  for await (const chunk of input) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readEmail(options, existing, input) {
+  const email = options.email?.trim() || existing?.email;
+  if (email) {
+    return email;
+  }
+  if (options.passwordStdin) {
+    throw new CliError("invalid_cli_usage", 'Pass "--email" when using "--password-stdin".');
+  }
+  const answer = (await prompt(input, "Email: ", false)).trim();
+  if (!answer) {
+    throw new CliError("invalid_cli_usage", "An email is required to log in.");
+  }
+  return answer;
+}
+async function readPassword(options, input) {
+  const password = options.passwordStdin ? (await readAll(input)).replace(/\r?\n$/, "") : await prompt(input, "Password: ", true);
+  if (!password) {
+    throw new CliError("invalid_cli_usage", "A password is required to log in.");
+  }
+  return password;
+}
+function resolveListingSession(filePath, options) {
+  try {
+    const profile = resolveProfile(readRuntimeConfig(filePath), {
+      profile: options.profile ?? readEnvProfile()
+    });
+    if (!isSessionProfile(profile)) {
+      throw new CliError(
+        "configuration_error",
+        `Profile "${profile.name}" is not a session profile. Run \`zinkee login\` or pass --profile with a session profile.`
+      );
+    }
+    return requireSession(profile);
+  } catch (error) {
+    toConfigurationError(filePath, error);
+  }
+}
+function registerSessionCommands(program, options = {}) {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = options.stdout ?? process.stdout;
+  const stdin = options.stdin ?? process.stdin;
+  program.command("login").description(
+    `Sign in with a Zinkee user and store a session profile (default "${DEFAULT_SESSION_PROFILE}")`
+  ).option("--email <email>", "user email (defaults to the stored one, else prompts)").option("--backend-url <url>", `web backend URL (default ${DEFAULT_PRODUCTION_BACKEND_URL})`).option("--base-url <url>", `Public API URL (default ${DEFAULT_PRODUCTION_BASE_URL})`).option("--password-stdin", "read the password from stdin").action(async function action() {
+    const loginOptions = this.optsWithGlobals();
+    if (!loginOptions.passwordStdin && !stdin.isTTY) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Stdin is not an interactive terminal: pass the password with "--password-stdin".'
+      );
+    }
+    const profileName = loginOptions.profile ?? DEFAULT_SESSION_PROFILE;
+    const config = readConfigOrEmpty(filePath);
+    const existing = config.profiles[profileName];
+    if (existing && !isSessionProfile(existing)) {
+      throw new CliError(
+        "configuration_error",
+        `Profile "${profileName}" uses an API key. Choose another name with --profile.`
+      );
+    }
+    const { backendUrl, baseUrl } = resolveLoginUrls(loginOptions, existing);
+    const email = await readEmail(loginOptions, existing, stdin);
+    const password = await readPassword(loginOptions, stdin);
+    const token = await signIn(backendUrl, email, password);
+    let nextConfig = setProfileConfig(config, profileName, {
+      type: SESSION_PROFILE_TYPE,
+      backendUrl,
+      baseUrl,
+      email,
+      sessionToken: token
+    });
+    if (!nextConfig.defaultProfile) {
+      nextConfig = setDefaultProfile(nextConfig, profileName);
+    }
+    writeConfig(nextConfig, filePath);
+    const expiresAt = decodeTokenExpiry(token)?.toISOString() ?? null;
+    if (loginOptions.json) {
+      emitJson(stdout, "login", { profile: profileName, email, backendUrl, baseUrl, expiresAt }, filePath);
+      return;
+    }
+    writeLine(
+      stdout,
+      expiresAt ? `Logged in as ${email} (profile ${profileName}, session valid until ${expiresAt}).` : `Logged in as ${email} (profile ${profileName}).`
+    );
+  });
+  program.command("logout").description(`Remove the stored session of a session profile (default "${DEFAULT_SESSION_PROFILE}")`).action(function action() {
+    const logoutOptions = this.optsWithGlobals();
+    const profileName = logoutOptions.profile ?? DEFAULT_SESSION_PROFILE;
+    const config = readConfigOrEmpty(filePath);
+    const profile = config.profiles[profileName];
+    if (!profile) {
+      throw new CliError("configuration_error", `Profile "${profileName}" not found in config.`);
+    }
+    if (!isSessionProfile(profile)) {
+      throw new CliError("configuration_error", `Profile "${profileName}" is not a session profile.`);
+    }
+    writeConfig(setProfileConfig(config, profileName, { sessionToken: void 0 }), filePath);
+    if (logoutOptions.json) {
+      emitJson(stdout, "logout", { profile: profileName, email: profile.email ?? null }, filePath);
+      return;
+    }
+    writeLine(
+      stdout,
+      `Removed the session of profile "${profileName}" from this machine. The server cannot revoke it, so it stays valid until it expires.`
+    );
+  });
+  const workspaces = program.command("workspaces").description("Browse organizations and workspaces with a session profile");
+  workspaces.command("list").description("List every organization and workspace visible to the session").action(async function action() {
+    const listOptions = this.optsWithGlobals();
+    const session = resolveListingSession(filePath, listOptions);
+    const data = (await listWorkspaces(session)).sort(
+      (left, right) => left.organizationName.localeCompare(right.organizationName) || left.workspaceName.localeCompare(right.workspaceName)
+    ).map(({ organizationId, organizationName, workspaceId, workspaceName, active }) => ({
+      organizationId,
+      organizationName,
+      workspaceId,
+      workspaceName,
+      active
+    }));
+    if (listOptions.json) {
+      emitJson(stdout, "workspaces list", data);
+      return;
+    }
+    printTable(
+      data.map((row) => ({
+        organization: row.organizationName,
+        workspace: row.workspaceName,
+        id: row.workspaceId,
+        active: row.active ? "yes" : "no"
+      })),
+      ["organization", "workspace", "id", "active"],
+      stdout
+    );
+  });
+}
+
 // src/commands/teamspace.ts
 import { readFileSync as readFileSync6 } from "fs";
 
@@ -5735,8 +6189,9 @@ var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 function buildProgram(options = {}) {
   const program = new Command4();
-  program.name("zinkee").description("CLI for Zinkee API v2").version(version).enablePositionalOptions().showHelpAfterError().option("--profile <name>", "select a profile from config").option("--base-url <url>", "override the configured base URL").option("--api-key <token>", "override the configured API key").option("--read-only", "run in read-only mode").option("--example", "show examples for a command").option("--json", "emit JSON output").option("--install-completion [shell]", "install shell completion (bash, zsh, fish, powershell)").option("--show-completion [shell]", "print shell completion script for the current shell");
+  program.name("zinkee").description("CLI for Zinkee API v2").version(version).enablePositionalOptions().showHelpAfterError().option("--profile <name>", "select a profile from config").option("--base-url <url>", "override the configured base URL").option("--api-key <token>", "override the configured API key").option("--workspace <workspace>", "workspace name or id for a session profile (or ZINKEE_WORKSPACE)").option("--read-only", "run in read-only mode").option("--example", "show examples for a command").option("--json", "emit JSON output").option("--install-completion [shell]", "install shell completion (bash, zsh, fish, powershell)").option("--show-completion [shell]", "print shell completion script for the current shell");
   registerProfilesCommands(program, options);
+  registerSessionCommands(program, options);
   registerAutomationsCommands(program, options);
   registerConfigCommands(program, options);
   registerDisplaysCommands(program, options);