@neta-art/cohub-cli 1.7.0 → 1.8.0

package/dist/commands/spaces.js

@@ -2,21 +2,36 @@ import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { basename, dirname, relative, resolve, sep } from "node:path";
-import { createClient } from "../client.js";
+import { resolveCohubEnvironment } from "@neta-art/cohub";
 import { uploadAvatarAsset } from "../avatar.js";
-import { table, json as outJson, ok, error, handleHttp } from "../output.js";
-function requireSpace(program) {
-    let current = program;
-    while (current) {
-        const opts = current.opts();
-        if (opts.space)
-            return String(opts.space);
-        current = current.parent ?? null;
-    }
-    return error("Missing required option", "Add -s, --space <id> to target a space");
-}
-const cliEnv = (process.env.ENV === "prod" ? "prod" : "dev");
+import { createClient } from "../client.js";
+import { table, json as outJson, jsonRequested, ok, error, handleHttp } from "../output.js";
+import { resolveSpace } from "../space.js";
+const cliEnv = resolveCohubEnvironment();
 const defaultIdleTtlSeconds = cliEnv === "prod" ? 12 * 60 * 60 : 10 * 60;
+const SPACE_ROLES = ["host", "builder", "guest"];
+function parseInteger(value, name, options = {}) {
+    if (!/^-?\d+$/.test(value.trim()))
+        return error(`Invalid ${name}`, `${name} must be an integer`);
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(parsed))
+        return error(`Invalid ${name}`, `${name} must be a safe integer`);
+    if (options.min !== undefined && parsed < options.min)
+        return error(`Invalid ${name}`, `${name} must be at least ${options.min}`);
+    if (options.max !== undefined && parsed > options.max)
+        return error(`Invalid ${name}`, `${name} must be at most ${options.max}`);
+    return parsed;
+}
+function parseChoice(value, name, choices) {
+    if (choices.includes(value))
+        return value;
+    return error(`Invalid ${name}`, `Use one of: ${choices.join(", ")}`);
+}
+function parseNullableRole(value, name) {
+    if (value === undefined || value === "null")
+        return null;
+    return parseChoice(value, name, SPACE_ROLES);
+}
 const parseAutoDestroy = (opts) => {
     const mode = opts.autoDestroy ?? (opts.idleTtl ? "idle" : undefined);
     if (!mode)
@@ -25,10 +40,7 @@ const parseAutoDestroy = (opts) => {
         return { mode: "never" };
     if (mode !== "idle")
         return error("Invalid auto destroy mode", "Use --auto-destroy idle or --auto-destroy never");
-    const ttlSeconds = Number.parseInt(opts.idleTtl ?? String(defaultIdleTtlSeconds), 10);
-    if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 60 || ttlSeconds > 30 * 24 * 60 * 60) {
-        return error("Invalid idle TTL", "--idle-ttl must be an integer between 60 and 2592000 seconds");
-    }
+    const ttlSeconds = parseInteger(opts.idleTtl ?? String(defaultIdleTtlSeconds), "idle TTL", { min: 60, max: 30 * 24 * 60 * 60 });
     return { mode: "idle", ttlSeconds };
 };
 const formatAutoDestroy = (policy) => {
@@ -93,7 +105,7 @@ async function putUploadEntry(entry, uploadUrl, headers) {
     }
 }
 async function uploadFiles(command, paths, opts) {
-    const spaceId = requireSpace(command);
+    const spaceId = resolveSpace(command);
     const client = createClient();
     try {
         const files = await collectUploadFiles(paths);
@@ -117,7 +129,7 @@ async function uploadFiles(command, paths, opts) {
         const result = await client.space(spaceId).files.completeUpload(plan.uploadId, {
             entries: plan.entries.map((entry) => ({ id: entry.id })),
         });
-        if (opts.json)
+        if (jsonRequested(opts))
             return outJson({ ...result, uploadId: plan.uploadId, files: files.length });
         ok(`Uploaded ${files.length} file${files.length === 1 ? "" : "s"}`);
     }
@@ -125,6 +137,21 @@ async function uploadFiles(command, paths, opts) {
         handleHttp(e);
     }
 }
+async function confirmRestart(opts) {
+    if (opts.yes)
+        return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return error("Confirmation required", "Pass --yes to restart the sandbox automatically.");
+    process.stdout.write("Changing mods restarts the sandbox and may interrupt running work. Continue? [y/N] ");
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+        break;
+    }
+    const answer = Buffer.concat(chunks).toString().trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes")
+        return error("Cancelled");
+}
 async function readPromptContent(words) {
     let content = words.join(" ");
     if (!content && !process.stdin.isTTY) {
@@ -144,11 +171,11 @@ async function sendPrompt(command, words, opts) {
         return error("Conflicting schedule", "Use only one of --delay-ms, --at, or --cron");
     if (opts.cron && !opts.timezone)
         return error("Missing timezone", "--timezone is required with --cron");
-    const spaceId = requireSpace(command);
+    const spaceId = resolveSpace(command);
     const client = createClient();
     try {
         const schedule = opts.delayMs
-            ? { mode: "delay", delayMs: Number.parseInt(opts.delayMs, 10) }
+            ? { mode: "delay", delayMs: parseInteger(opts.delayMs, "delay", { min: 1 }) }
             : opts.at
                 ? { mode: "at", sendAt: opts.at }
                 : opts.cron
@@ -162,7 +189,7 @@ async function sendPrompt(command, words, opts) {
             provider: opts.provider,
             schedule,
         });
-        if (opts.json)
+        if (jsonRequested(opts))
             return outJson(result);
         if (result.mode === "immediate")
             return ok(`Prompt sent — sessionId: ${result.sessionId}, turnId: ${result.turnId}`);
@@ -201,7 +228,7 @@ export function registerSpaces(program) {
         const client = createClient();
         try {
             const items = await client.spaces.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(items);
             table(items, [
                 { key: "id", label: "ID" },
@@ -222,7 +249,7 @@ export function registerSpaces(program) {
         const client = createClient();
         try {
             const space = await client.spaces.get(id);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(space);
             table([space], [
                 { key: "id", label: "ID" },
@@ -254,7 +281,7 @@ export function registerSpaces(program) {
                 description: opts.description,
                 ...(autoDestroy ? { config: { sandbox: { autoDestroy } } } : {}),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             ok(`Space created: ${result.space.id}`);
             table([result.space], [
@@ -287,12 +314,12 @@ export function registerSpaces(program) {
         .description("Upload the space avatar")
         .option("--json", "Output as JSON")
         .action(async (path, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const asset = await uploadAvatarAsset({ client, purpose: "space_avatar", spaceId, path });
             const result = await client.space(spaceId).profile({ avatarUrl: asset.publicUrl });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson({ ...result, asset });
             ok("Space avatar updated");
         }
@@ -313,13 +340,13 @@ export function registerSpaces(program) {
             const autoDestroy = parseAutoDestroy(opts);
             if (autoDestroy) {
                 const result = await client.space(id).updateConfig({ sandbox: { autoDestroy } });
-                if (opts.json)
+                if (jsonRequested(opts))
                     return outJson(result);
                 ok(`Space config updated — sandbox auto destroy: ${formatAutoDestroy(autoDestroy)}`);
                 return;
             }
             const result = await client.space(id).getConfig();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             table([{ key: "sandbox.autoDestroy", value: formatAutoDestroy(result.config.sandbox.autoDestroy) }], [
                 { key: "key", label: "Key" },
@@ -363,11 +390,11 @@ export function registerSpaces(program) {
         .description("Space usage statistics (default: 30 days)")
         .option("--json", "Output as JSON")
         .action(async (days, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
-            const usage = await client.space(spaceId).usage.get(Number.parseInt(days ?? "30", 10));
-            if (opts.json)
+            const usage = await client.space(spaceId).usage.get(parseInteger(days ?? "30", "days", { min: 1 }));
+            if (jsonRequested(opts))
                 return outJson(usage);
             console.log("\n  Summary:");
             table([usage.summary], [
@@ -387,23 +414,23 @@ function registerMods(spacesCmd) {
     const modsCmd = spacesCmd
         .command("mods")
         .description("Manage space mods")
-        .hook("preAction", () => { requireSpace(spacesCmd); });
+        .hook("preAction", () => { resolveSpace(spacesCmd); });
     modsCmd
         .command("ls")
         .alias("list")
         .description("List mods")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result.items);
             table(result.items, [
                 { key: "id", label: "ID" },
                 { key: "modSpaceName", label: "Name" },
-                { key: "modSpaceId", label: "Space" },
+                { key: "mountPath", label: "Mount" },
                 { key: "enabled", label: "On" },
             ]);
         }
@@ -414,15 +441,19 @@ function registerMods(spacesCmd) {
     modsCmd
         .command("add <modSpaceId>")
         .description("Add a mod")
+        .option("--name <name>", "Display name")
+        .option("--slug <slug>", "Mount slug")
+        .option("-y, --yes", "Confirm sandbox restart")
         .option("--json", "Output as JSON")
         .action(async (modSpaceId, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        await confirmRestart(opts);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
-            const result = await client.space(spaceId).mods.create({ modSpaceId });
-            if (opts.json)
+            const result = await client.space(spaceId).mods.create({ modSpaceId, name: opts.name, mountSlug: opts.slug });
+            if (jsonRequested(opts))
                 return outJson(result);
-            ok("Mod added");
+            ok(`Mod added — ${result.item.mountPath}; sandbox restarting`);
         }
         catch (e) {
             handleHttp(e);
@@ -431,15 +462,17 @@ function registerMods(spacesCmd) {
     modsCmd
         .command("enable <modId>")
         .description("Enable a mod")
+        .option("-y, --yes", "Confirm sandbox restart")
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        await confirmRestart(opts);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.update(modId, { enabled: true });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
-            ok("Mod enabled");
+            ok("Mod enabled; sandbox restarting");
         }
         catch (e) {
             handleHttp(e);
@@ -448,15 +481,17 @@ function registerMods(spacesCmd) {
     modsCmd
         .command("disable <modId>")
         .description("Disable a mod")
+        .option("-y, --yes", "Confirm sandbox restart")
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        await confirmRestart(opts);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.update(modId, { enabled: false });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
-            ok("Mod disabled");
+            ok("Mod disabled; sandbox restarting");
         }
         catch (e) {
             handleHttp(e);
@@ -466,15 +501,17 @@ function registerMods(spacesCmd) {
         .command("rm <modId>")
         .alias("remove")
         .description("Remove a mod")
+        .option("-y, --yes", "Confirm sandbox restart")
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        await confirmRestart(opts);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.remove(modId);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
-            ok("Mod removed");
+            ok("Mod removed; sandbox restarting");
         }
         catch (e) {
             handleHttp(e);
@@ -486,18 +523,18 @@ function registerFiles(spacesCmd) {
     const filesCmd = spacesCmd
         .command("files")
         .description("File operations")
-        .hook("preAction", () => { requireSpace(spacesCmd); });
+        .hook("preAction", () => { resolveSpace(spacesCmd); });
     filesCmd
         .command("ls [path]")
         .alias("list")
         .description("List directory tree")
         .option("--json", "Output as JSON")
         .action(async (path, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const tree = await client.space(spaceId).files.list(path ?? "");
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(tree);
             if (tree.entries.length === 0) {
                 console.log("  (empty)");
@@ -518,7 +555,7 @@ function registerFiles(spacesCmd) {
         .command("cat <path>")
         .description("Read file content")
         .action(async (path) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const file = await client.space(spaceId).files.read(path);
@@ -548,7 +585,7 @@ function registerFiles(spacesCmd) {
         }
         if (!content)
             return error("No content provided", "Use -c or pipe via stdin");
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).files.write({
@@ -572,7 +609,7 @@ function registerFiles(spacesCmd) {
         .command("mkdir <path>")
         .description("Create a directory")
         .action(async (path) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).files.createDir(path);
@@ -587,7 +624,7 @@ function registerFiles(spacesCmd) {
         .description("Delete a file or directory")
         .option("-r, --recursive", "Delete recursively")
         .action(async (path, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).files.delete(path, opts.recursive ?? false);
@@ -601,7 +638,7 @@ function registerFiles(spacesCmd) {
         .command("mv <from> <to>")
         .description("Move or rename")
         .action(async (from, to) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).files.move({ fromPath: from, toPath: to });
@@ -617,18 +654,18 @@ function registerSessions(spacesCmd) {
     const sessionsCmd = spacesCmd
         .command("sessions")
         .description("Browse sessions and turns")
-        .hook("preAction", () => { requireSpace(spacesCmd); });
+        .hook("preAction", () => { resolveSpace(spacesCmd); });
     sessionsCmd
         .command("ls")
         .alias("list")
         .description("List sessions")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).sessions.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.sessions.length === 0) {
                 console.log("  (empty)");
@@ -650,11 +687,11 @@ function registerSessions(spacesCmd) {
         .description("Create a session")
         .option("--json", "Output as JSON")
         .action(async (title, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).sessions.create({ title });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             ok(`Session created: ${result.session.id}`);
             table([result.session], [
@@ -671,11 +708,11 @@ function registerSessions(spacesCmd) {
         .description("Session details")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(id).get();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             table([result.session], [
                 { key: "id", label: "ID" },
@@ -693,7 +730,7 @@ function registerSessions(spacesCmd) {
         .command("rename <id> <name>")
         .description("Rename a session")
         .action(async (id, name) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).session(id).rename(name);
@@ -709,13 +746,13 @@ function registerSessions(spacesCmd) {
         .description("Stream realtime session events")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         const session = client.space(spaceId).session(id);
         process.stdout.write("  Listening for events...\n\n");
         let lastAppendPath = null;
         session.on("turn.patch", (e) => {
-            if (opts.json) {
+            if (jsonRequested(opts)) {
                 console.log(JSON.stringify(e));
             }
             else {
@@ -742,7 +779,7 @@ function registerSessions(spacesCmd) {
         });
         session.on("turn.error", (e) => {
             process.stderr.write(`\n  ✗ Error\n`);
-            if (opts.json)
+            if (jsonRequested(opts))
                 process.stderr.write(`${JSON.stringify(e)}\n`);
             process.exit(1);
         });
@@ -764,15 +801,15 @@ function registerTurns(sessionsCmd) {
         .option("--limit <n>", "Page size", "30")
         .option("--json", "Output as JSON")
         .action(async (sessionId, opts) => {
-        const spaceId = requireSpace(sessionsCmd);
+        const spaceId = resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.listPaginated({
-                cursor: opts.cursor === undefined ? undefined : Number.parseInt(opts.cursor, 10),
-                direction: opts.direction,
-                limit: Number.parseInt(opts.limit ?? "30", 10),
+                cursor: opts.cursor === undefined ? undefined : parseInteger(opts.cursor, "cursor", { min: 0 }),
+                direction: parseChoice(opts.direction ?? "older", "direction", ["older", "newer"]),
+                limit: parseInteger(opts.limit ?? "30", "limit", { min: 1, max: 100 }),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.turns.length === 0)
                 return console.log("  No turns found");
@@ -796,11 +833,11 @@ function registerTurns(sessionsCmd) {
         .description("Show turn details")
         .option("--json", "Output as JSON")
         .action(async (sessionId, turnId, opts) => {
-        const spaceId = requireSpace(sessionsCmd);
+        const spaceId = resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.get(turnId);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             table([result.turn], [
                 { key: "sequence", label: "Seq" },
@@ -827,14 +864,14 @@ function registerTurns(sessionsCmd) {
         .option("--limit <n>", "Page size", "100")
         .option("--json", "Output as JSON")
         .action(async (sessionId, opts) => {
-        const spaceId = requireSpace(sessionsCmd);
+        const spaceId = resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.index({
-                cursor: opts.cursor === undefined ? undefined : Number.parseInt(opts.cursor, 10),
-                limit: Number.parseInt(opts.limit ?? "100", 10),
+                cursor: opts.cursor === undefined ? undefined : parseInteger(opts.cursor, "cursor", { min: 0 }),
+                limit: parseInteger(opts.limit ?? "100", "limit", { min: 1, max: 500 }),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.turns.length === 0)
                 return console.log("  No turns found");
@@ -861,18 +898,18 @@ function registerTurns(sessionsCmd) {
         .option("--after <n>", "Turns after anchor", "20")
         .option("--json", "Output as JSON")
         .action(async (sessionId, opts) => {
-        const spaceId = requireSpace(sessionsCmd);
+        const spaceId = resolveSpace(sessionsCmd);
         if (!opts.sequence && !opts.turn)
             return error("Missing anchor", "Use --sequence <n> or --turn <id>");
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.window({
-                sequence: opts.sequence === undefined ? undefined : Number.parseInt(opts.sequence, 10),
+                sequence: opts.sequence === undefined ? undefined : parseInteger(opts.sequence, "sequence", { min: 0 }),
                 turnId: opts.turn,
-                before: Number.parseInt(opts.before ?? "10", 10),
-                after: Number.parseInt(opts.after ?? "20", 10),
+                before: parseInteger(opts.before ?? "10", "before", { min: 0, max: 200 }),
+                after: parseInteger(opts.after ?? "20", "after", { min: 0, max: 200 }),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.turns.length === 0)
                 return console.log("  No turns found");
@@ -901,7 +938,7 @@ function registerSessionAccess(sessionsCmd) {
         const client = createClient();
         try {
             const policy = await client.sessionAccess.get(id);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(policy);
             table([policy], [
                 { key: "signed_in_user", label: "Signed-in" },
@@ -921,9 +958,9 @@ function registerSessionAccess(sessionsCmd) {
         const client = createClient();
         try {
             const policy = await client.sessionAccess.set(id, {
-                anonymous_user: (opts.anonymous ?? null),
+                anonymous_user: parseNullableRole(opts.anonymous, "anonymous role"),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(policy);
             ok("Session access updated");
             table([policy], [
@@ -954,18 +991,18 @@ function registerMembers(spacesCmd) {
     const memCmd = spacesCmd
         .command("members")
         .description("Member management")
-        .hook("preAction", () => { requireSpace(spacesCmd); });
+        .hook("preAction", () => { resolveSpace(spacesCmd); });
     memCmd
         .command("ls")
         .alias("list")
         .description("List space members")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).members.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.items.length === 0) {
                 console.log("  (empty)");
@@ -985,10 +1022,10 @@ function registerMembers(spacesCmd) {
         .command("update <userId> <role>")
         .description("Change member role (host | builder | guest)")
         .action(async (userId, role) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
-            await client.space(spaceId).members.update(userId, role);
+            await client.space(spaceId).members.update(userId, parseChoice(role, "role", SPACE_ROLES));
             ok(`${userId} → ${role}`);
         }
         catch (e) {
@@ -999,7 +1036,7 @@ function registerMembers(spacesCmd) {
         .command("remove <userId>")
         .description("Remove a member")
         .action(async (userId) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).members.remove(userId);
@@ -1015,17 +1052,17 @@ function registerAccess(spacesCmd) {
     const accCmd = spacesCmd
         .command("access")
         .description("Access control")
-        .hook("preAction", () => { requireSpace(spacesCmd); });
+        .hook("preAction", () => { resolveSpace(spacesCmd); });
     accCmd
         .command("get")
         .description("Get access policy")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const policy = await client.space(spaceId).access.get();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(policy);
             table([policy], [
                 { key: "signed_in_user", label: "Signed-in" },
@@ -1043,14 +1080,14 @@ function registerAccess(spacesCmd) {
         .option("--anonymous <role>", "Role for anonymous users (host|builder|guest|null)")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const policy = await client.space(spaceId).access.set({
-                signed_in_user: (opts.signedIn ?? null),
-                anonymous_user: (opts.anonymous ?? null),
+                signed_in_user: parseNullableRole(opts.signedIn, "signed-in role"),
+                anonymous_user: parseNullableRole(opts.anonymous, "anonymous role"),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(policy);
             ok("Access policy updated");
             table([policy], [
@@ -1068,18 +1105,18 @@ function registerCheckpoints(spacesCmd) {
     const cpCmd = spacesCmd
         .command("checkpoints")
         .description("Checkpoint management")
-        .hook("preAction", () => { requireSpace(spacesCmd); });
+        .hook("preAction", () => { resolveSpace(spacesCmd); });
     cpCmd
         .command("ls")
         .alias("list")
         .description("List checkpoints")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).checkpoints.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.checkpoints.length === 0) {
                 console.log("  (empty)");
@@ -1101,11 +1138,11 @@ function registerCheckpoints(spacesCmd) {
         .description("Checkpoint details")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).checkpoints.get(id);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             table([result.checkpoint], [
                 { key: "id", label: "ID" },
@@ -1124,11 +1161,11 @@ function registerCheckpoints(spacesCmd) {
         .description("Create a checkpoint")
         .option("--json", "Output as JSON")
         .action(async (description, opts) => {
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).checkpoints.create(description ?? null);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             ok(`Checkpoint created — taskRunId: ${result.taskRunId}`);
         }