@neta-art/cohub-cli 1.7.1 → 1.8.0

package/README.md

@@ -129,6 +129,8 @@ cohub search "query" --limit 20 --json
 ```bash
 cohub models ls --json
 cohub models ls --model-type multimodal --json
+cohub models show <model>
+cohub models show <model> --json
 
 cohub generate "a calm lake at sunrise" \
   --model <model> \

package/dist/auth.d.ts

@@ -30,7 +30,9 @@ export declare class AuthRequiredError extends Error {
 export declare const readAuthSession: () => AuthSession | null;
 export declare const clearAuthSession: () => void;
 export declare const authSource: () => AuthSource;
-export declare function resolveAccessToken(): Promise<string | null>;
+export declare function resolveAccessToken(options?: {
+    forceRefresh?: boolean;
+}): Promise<string | null>;
 export declare function requireAccessToken(): Promise<string>;
 export declare function refreshAccessToken(session?: AuthSession | null): Promise<string | null>;
 export declare function requestDeviceCode(): Promise<DeviceCode>;

package/dist/auth.js

@@ -125,14 +125,14 @@ export const authSource = () => {
         return "logto";
     return null;
 };
-export async function resolveAccessToken() {
+export async function resolveAccessToken(options) {
     const executionToken = process.env.COHUB_EXECUTION_TOKEN?.trim();
     if (executionToken)
         return executionToken;
     const session = readAuthSession();
     if (!session)
         throw new AuthRequiredError();
-    if (session.accessTokenExpiresAt - Date.now() > EXPIRY_SKEW_MS)
+    if (!options?.forceRefresh && session.accessTokenExpiresAt - Date.now() > EXPIRY_SKEW_MS)
         return session.accessToken;
     return refreshAccessToken(session);
 }

package/dist/commands/auth.js

@@ -1,6 +1,6 @@
 import { authSource, loginWithDeviceFlow, readAuthSession, refreshAccessToken, requestDeviceCode, revokeAndClearAuthSession, verifyDeviceCode } from "../auth.js";
 import { createClient } from "../client.js";
-import { table, json as outJson, ok, error, spinner, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, ok, error, spinner, handleHttp } from "../output.js";
 export function registerAuth(program) {
     const auth = program.command("auth").description("Authentication management");
     auth
@@ -9,8 +9,8 @@ export function registerAuth(program) {
         .option("--request-code", "Request a device code without polling")
         .option("--verify-code", "Exchange a previously requested device code")
         .option("--json", "Output as JSON")
-        .action(async (opts, command) => {
-        const asJson = Boolean(opts.json || command.parent?.optsWithGlobals().json);
+        .action(async (opts) => {
+        const asJson = jsonRequested(opts);
         if (opts.requestCode && opts.verifyCode) {
             return error("Conflicting options", "Use only one of --request-code or --verify-code");
         }
@@ -43,8 +43,8 @@ export function registerAuth(program) {
         .command("whoami")
         .description("Show current user info")
         .option("--json", "Output as JSON")
-        .action(async (opts, command) => {
-        const asJson = Boolean(opts.json || command.parent?.optsWithGlobals().json);
+        .action(async (opts) => {
+        const asJson = jsonRequested(opts);
         return showSignedIn(asJson);
     });
     auth
@@ -80,11 +80,11 @@ async function showSignedIn(asJson) {
     if (!source)
         return error("Not authenticated", "Run `cohub auth login`.");
     const client = createClient();
-    const sp = spinner();
-    sp.start("Fetching user info");
+    const sp = asJson ? null : spinner();
+    sp?.start("Fetching user info");
     try {
         const user = await client.user.getMe();
-        sp.stop("Done");
+        sp?.stop("Done");
         const session = readAuthSession();
         const payload = {
             source,
@@ -93,22 +93,77 @@ async function showSignedIn(asJson) {
         };
         if (asJson)
             return outJson(payload);
-        const u = user;
+        const u = flattenMeForTable(user);
         console.log(`  Auth source: ${source}`);
         console.log(`  Token: ${payload.refreshable ? "refreshable" : "ephemeral"}\n`);
         table([u], [
-            { key: "id", label: "ID" },
+            { key: "uuid", label: "UUID" },
             { key: "username", label: "Username" },
-            { key: "name", label: "Name" },
+            { key: "displayName", label: "Name" },
             { key: "email", label: "Email" },
-            { key: "created_at", label: "Created" },
         ]);
     }
     catch (e) {
-        sp.stop("Failed");
+        if (source === "execution-token") {
+            sp?.stop("Using local execution token");
+            return showExecutionTokenFallback(asJson);
+        }
+        sp?.stop("Failed");
         handleHttp(e);
     }
 }
+function flattenMeForTable(user) {
+    const profile = user.profile && typeof user.profile === "object" ? user.profile : {};
+    return {
+        uuid: user.uuid,
+        username: profile.username,
+        displayName: profile.displayName,
+        email: user.email,
+    };
+}
+function decodeExecutionTokenPayload() {
+    const token = process.env.COHUB_EXECUTION_TOKEN?.trim();
+    const payload = token?.split(".")[1];
+    if (!payload)
+        return null;
+    try {
+        const decoded = Buffer.from(payload, "base64url").toString("utf-8");
+        const parsed = JSON.parse(decoded);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function showExecutionTokenFallback(asJson) {
+    const payload = decodeExecutionTokenPayload();
+    const execution = {
+        actorUserId: typeof payload?.actorUserId === "string" ? payload.actorUserId : null,
+        spaceId: typeof payload?.spaceId === "string" ? payload.spaceId : null,
+        sessionId: typeof payload?.sessionId === "string" ? payload.sessionId : null,
+        source: typeof payload?.source === "string" ? payload.source : null,
+        expiresAt: typeof payload?.exp === "number" ? new Date(payload.exp * 1000).toISOString() : null,
+    };
+    const result = {
+        source: "execution-token",
+        refreshable: false,
+        user: execution.actorUserId ? { uuid: execution.actorUserId } : null,
+        execution,
+    };
+    if (asJson) {
+        outJson(result);
+        return;
+    }
+    console.log("  Auth source: execution-token");
+    console.log("  Token: ephemeral\n");
+    table([execution], [
+        { key: "actorUserId", label: "Actor" },
+        { key: "spaceId", label: "Space" },
+        { key: "sessionId", label: "Session" },
+        { key: "source", label: "Source" },
+        { key: "expiresAt", label: "Expires" },
+    ]);
+}
 function printDeviceCode(code) {
     console.log("\nOpen this URL to sign in:\n");
     console.log(`  ${code.verificationUriComplete}\n`);

package/dist/commands/channels.js

@@ -1,5 +1,5 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, ok, error, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, ok, error, handleHttp } from "../output.js";
 export function registerChannels(program) {
     const cmd = program.command("channels", { hidden: true }).description("Channel integrations");
     cmd
@@ -11,7 +11,7 @@ export function registerChannels(program) {
         const client = createClient();
         try {
             const items = await client.channels.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(items);
             if (items.length === 0)
                 return console.log("  (empty)");
@@ -50,7 +50,7 @@ export function registerChannels(program) {
                 name: opts.name,
                 credentials,
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             ok("Channel created");
         }

package/dist/commands/cron-jobs.js

@@ -1,5 +1,5 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, ok, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, ok, error, handleHttp } from "../output.js";
 export function registerCronJobs(program) {
     const cmd = program.command("cron-jobs", { hidden: true }).description("Scheduled prompt jobs");
     cmd
@@ -11,7 +11,7 @@ export function registerCronJobs(program) {
         const client = createClient();
         try {
             const result = await client.cronJobs.list(spaceId);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.jobs.length === 0)
                 return console.log("  (empty)");
@@ -44,6 +44,8 @@ export function registerCronJobs(program) {
         .command("toggle <id> <on|off>")
         .description("Enable or disable a cron job")
         .action(async (id, state) => {
+        if (state !== "on" && state !== "off")
+            return error("Invalid state", "Use on or off");
         const enabled = state === "on";
         const client = createClient();
         try {
@@ -62,7 +64,7 @@ export function registerCronJobs(program) {
         const client = createClient();
         try {
             const result = await client.cronJobs.runs(id);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.runs.length === 0)
                 return console.log("  (empty)");

package/dist/commands/generations.js

@@ -1,7 +1,8 @@
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import { createClient } from "../client.js";
-import { json as outJson, ok, handleHttp } from "../output.js";
+import { resolveSpace } from "../space.js";
+import { json as outJson, jsonRequested, ok, error, handleHttp, spinner } from "../output.js";
 const mimeByExt = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -108,43 +109,72 @@ function printGeneration(output) {
             console.log(`${block.type}: ${block.source.space_id}:${block.source.path}`);
     }
 }
+function parseTimeoutMs(value) {
+    if (!value)
+        return undefined;
+    if (!/^\d+$/.test(value.trim()))
+        return error("Invalid timeout", "--timeout-ms must be a positive integer");
+    const timeoutMs = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+        return error("Invalid timeout", "--timeout-ms must be a positive integer");
+    return timeoutMs;
+}
 export function registerGenerations(program) {
     program
         .command("generate")
         .description("Generate multimodal outputs")
         .argument("<prompt>", "Prompt text")
-        .requiredOption("--model <model>", "Multimodal model ID from `cohub models ls --model-type multimodal`")
+        .requiredOption("-m, --model <model>", "Multimodal model ID from `cohub models ls --model-type multimodal`")
         .option("--image <path-or-url>", "Image input file path or URL; repeatable", collect, [])
         .option("--video <path-or-url>", "Video input file path or URL; repeatable", collect, [])
         .option("--audio <path-or-url>", "Audio input file path or URL; repeatable", collect, [])
         .option("--param <key=value>", "Generation parameter; repeatable, values may be JSON/number/boolean", collect, [])
         .option("--parameters <json>", "Generation parameters as a JSON object")
         .option("--metadata <json>", "Metadata as a JSON object")
-        .option("--output <path>", "Save generated output to a file or directory")
+        .option("-o, --output <path>", "Save generated output to a file or directory")
+        .option("--async", "Queue the generation task and return immediately")
+        .option("--timeout-ms <ms>", "Maximum time to wait in synchronous mode")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
 
 Examples:
   cohub models ls --model-type multimodal
-  cohub generate "A calm lake at sunrise" --model <model> --output lake.png
-  cohub generate "Restyle this image" --model <model> --image input.png --param size=1024x1024
+  cohub -s <space-id> generate "A calm lake at sunrise" -m <model> -o lake.png
+  COHUB_SPACE_ID=<space-id> cohub generate "Restyle this image" -m <model> --image input.png
+  cohub -s <space-id> generate "A calm lake" -m <model> --async
 `)
         .action(async (prompt, opts) => {
         try {
+            const spaceId = resolveSpace(program);
             const content = [{ type: "text", text: prompt }];
             content.push(...await Promise.all(opts.image.map((value) => contentFromPathOrUrl("image", value))));
             content.push(...await Promise.all(opts.video.map((value) => contentFromPathOrUrl("video", value))));
             content.push(...await Promise.all(opts.audio.map((value) => contentFromPathOrUrl("audio", value))));
-            const generation = await createClient().generations.create({
+            const client = createClient();
+            const created = await client.generations.create({
+                spaceId,
                 model: opts.model,
                 content,
                 parameters: parseParams(opts.param, opts.parameters),
                 metadata: opts.metadata ? JSON.parse(opts.metadata) : undefined,
             });
-            const savedPaths = opts.output && generation.output ? await saveOutputs(generation.output, opts.output) : [];
-            if (opts.json)
-                return outJson(savedPaths.length > 0 ? { ...generation, savedPaths } : generation);
-            printGeneration(generation.output ?? []);
+            if (opts.async) {
+                if (jsonRequested(opts))
+                    return outJson(created);
+                return ok(`Generation queued — taskRunId: ${created.taskRunId}`);
+            }
+            const spin = spinner();
+            if (!jsonRequested(opts))
+                spin.start("Generating");
+            const result = await client.generations.wait(created.taskRunId, {
+                timeoutMs: parseTimeoutMs(opts.timeoutMs),
+            });
+            if (!jsonRequested(opts))
+                spin.stop("Generation completed");
+            const savedPaths = opts.output ? await saveOutputs(result.output, opts.output) : [];
+            if (jsonRequested(opts))
+                return outJson(savedPaths.length > 0 ? { ...result, taskRunId: created.taskRunId, savedPaths } : { ...result, taskRunId: created.taskRunId });
+            printGeneration(result.output);
             if (savedPaths.length > 0)
                 ok(`Saved to ${savedPaths.join(", ")}`);
         }

package/dist/commands/models.js

@@ -1,5 +1,69 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, error, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, error, handleHttp } from "../output.js";
+function toMultimodalModelSummary(model) {
+    return {
+        model: model.model,
+        ...(model.title ? { title: model.title } : {}),
+        ...(model.description ? { description: model.description } : {}),
+    };
+}
+function printSection(title, lines) {
+    if (lines.length === 0)
+        return;
+    console.log(`\n${title}`);
+    for (const line of lines)
+        console.log(`  ${line}`);
+}
+function formatContentSpec(spec) {
+    const details = [];
+    details.push(spec.required === false ? "optional" : "required");
+    if (typeof spec.min === "number")
+        details.push(`min ${spec.min}`);
+    if (typeof spec.max === "number")
+        details.push(`max ${spec.max}`);
+    if (spec.sources?.length)
+        details.push(`sources: ${spec.sources.join(", ")}`);
+    if (spec.merge)
+        details.push(`merge: ${spec.merge}`);
+    if (spec.description)
+        details.push(spec.description);
+    return `${spec.type}${details.length > 0 ? ` — ${details.join("; ")}` : ""}`;
+}
+function formatParameter(name, spec) {
+    const lines = [`${name}`];
+    const details = [`type: ${spec.type}`];
+    if (spec.optional)
+        details.push("optional");
+    if ("default" in spec && spec.default !== undefined)
+        details.push(`default: ${String(spec.default)}`);
+    if ("min" in spec && typeof spec.min === "number")
+        details.push(`min: ${spec.min}`);
+    if ("max" in spec && typeof spec.max === "number")
+        details.push(`max: ${spec.max}`);
+    if ("enum" in spec && spec.enum?.length)
+        details.push(`values: ${spec.enum.join(", ")}`);
+    lines.push(`  ${details.join("; ")}`);
+    if (spec.description)
+        lines.push(`  ${spec.description}`);
+    if ("examples" in spec && spec.examples?.length)
+        lines.push(`  examples: ${spec.examples.map(String).join(", ")}`);
+    return lines;
+}
+function printMultimodalModel(model) {
+    console.log(model.title ?? model.model);
+    printSection("Model", [model.model]);
+    if (model.description)
+        printSection("Description", [model.description]);
+    printSection("Input", model.content.input.map(formatContentSpec));
+    const parameterLines = Object.entries(model.parameters ?? {}).flatMap(([name, spec]) => formatParameter(name, spec));
+    printSection("Parameters", parameterLines);
+    const examples = model.examples ?? [];
+    printSection("Examples", examples.map((example, index) => {
+        const title = example.title ? `${example.title}: ` : "";
+        const prompt = example.request.content.find((block) => block.type === "text")?.text;
+        return `${index + 1}. ${title}${prompt ? `"${prompt}"` : example.request.model}`;
+    }));
+}
 export function registerModels(program) {
     const cmd = program
         .command("models")
@@ -10,6 +74,8 @@ Examples:
   cohub models ls
   cohub models ls --model-type multimodal
   cohub models ls --model-type multimodal --json
+  cohub models show <model>
+  cohub models show <model> --json
 `);
     cmd
         .command("ls")
@@ -22,9 +88,10 @@ Examples:
         try {
             if (opts.modelType === "multimodal") {
                 const response = await client.models.listMultimodal();
-                if (opts.json)
-                    return outJson(response);
-                table(response.models, [
+                const models = response.models.map(toMultimodalModelSummary);
+                if (jsonRequested(opts))
+                    return outJson({ models });
+                table(models, [
                     { key: "model", label: "Model" },
                     { key: "title", label: "Title" },
                     { key: "description", label: "Description" },
@@ -35,7 +102,7 @@ Examples:
                 return error("Invalid model type", "Use --model-type llm or --model-type multimodal");
             }
             const catalog = await client.models.list();
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(catalog);
             // catalog is Record<provider, ModelCatalogEntry[]>
             for (const [provider, entries] of Object.entries(catalog)) {
@@ -51,4 +118,25 @@ Examples:
             handleHttp(e);
         }
     });
+    cmd
+        .command("show")
+        .description("Show full multimodal model details")
+        .argument("<model>", "Multimodal model ID")
+        .option("--json", "Output as JSON")
+        .action(async (modelId, opts) => {
+        const client = createClient();
+        try {
+            const response = await client.models.listMultimodal();
+            const model = response.models.find((item) => item.model === modelId);
+            if (!model) {
+                return error("Model not found", `No multimodal model named ${modelId}`);
+            }
+            if (jsonRequested(opts))
+                return outJson(model);
+            printMultimodalModel(model);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
 }

package/dist/commands/profile.js

@@ -1,6 +1,6 @@
 import { uploadAvatarAsset } from "../avatar.js";
 import { createClient } from "../client.js";
-import { json as outJson, ok, handleHttp } from "../output.js";
+import { json as outJson, jsonRequested, ok, handleHttp } from "../output.js";
 export function registerProfile(program) {
     const profileCmd = program.command("profile").description("Manage your profile");
     profileCmd
@@ -12,7 +12,7 @@ export function registerProfile(program) {
         try {
             const asset = await uploadAvatarAsset({ client, purpose: "user_avatar", path });
             const result = await client.user.updateProfile({ avatarUrl: asset.publicUrl });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson({ ...result, asset });
             ok("Avatar updated");
         }

package/dist/commands/prompts.js

@@ -1,5 +1,5 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, handleHttp } from "../output.js";
 export function registerPrompts(program) {
     const cmd = program.command("prompts").description("Prompt template management");
     cmd
@@ -12,7 +12,7 @@ export function registerPrompts(program) {
         const client = createClient();
         try {
             const result = await client.prompts.list({ spaceId: opts.space });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.prompts.length === 0)
                 return console.log("  (empty)");

package/dist/commands/search.js

@@ -1,5 +1,5 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, error, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, error, handleHttp } from "../output.js";
 const DEFAULT_LIMIT = 20;
 const MAX_TITLE_LENGTH = 72;
 const MAX_CONTEXT_LENGTH = 42;
@@ -81,7 +81,7 @@ Examples:
                 types: input.types,
                 spaceId: input.spaceId,
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.degraded) {
                 process.stderr.write("  Search is temporarily degraded; results may be incomplete.\n");

package/dist/commands/session-access.js

@@ -1,5 +1,13 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, error, handleHttp } from "../output.js";
+const SPACE_ROLES = ["host", "builder", "guest"];
+function parseAnonymousRole(value) {
+    if (value === undefined || value === "null")
+        return null;
+    if (SPACE_ROLES.includes(value))
+        return value;
+    return error("Invalid anonymous role", "Use one of: host, builder, guest, null");
+}
 export function registerSessionAccess(program) {
     const cmd = program
         .command("session-access")
@@ -12,7 +20,7 @@ export function registerSessionAccess(program) {
         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" },
@@ -32,9 +40,9 @@ export function registerSessionAccess(program) {
         const client = createClient();
         try {
             const policy = await client.sessionAccess.set(id, {
-                anonymous_user: (opts.anonymous ?? null),
+                anonymous_user: parseAnonymousRole(opts.anonymous),
             });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(policy);
             console.log("Session access updated");
             table([policy], [

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"}`);
     }
@@ -159,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
@@ -177,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}`);
@@ -216,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" },
@@ -237,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" },
@@ -269,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], [
@@ -302,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");
         }
@@ -328,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" },
@@ -378,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], [
@@ -402,18 +414,18 @@ 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" },
@@ -435,11 +447,11 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modSpaceId, opts) => {
         await confirmRestart(opts);
-        const spaceId = requireSpace(spacesCmd);
+        const spaceId = resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.create({ modSpaceId, name: opts.name, mountSlug: opts.slug });
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             ok(`Mod added — ${result.item.mountPath}; sandbox restarting`);
         }
@@ -454,11 +466,11 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
         await confirmRestart(opts);
-        const spaceId = requireSpace(spacesCmd);
+        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; sandbox restarting");
         }
@@ -473,11 +485,11 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
         await confirmRestart(opts);
-        const spaceId = requireSpace(spacesCmd);
+        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; sandbox restarting");
         }
@@ -493,11 +505,11 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
         await confirmRestart(opts);
-        const spaceId = requireSpace(spacesCmd);
+        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; sandbox restarting");
         }
@@ -511,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)");
@@ -543,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);
@@ -573,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({
@@ -597,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);
@@ -612,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);
@@ -626,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 });
@@ -642,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)");
@@ -675,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], [
@@ -696,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" },
@@ -718,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);
@@ -734,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 {
@@ -767,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);
         });
@@ -789,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");
@@ -821,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" },
@@ -852,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");
@@ -886,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");
@@ -926,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" },
@@ -946,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], [
@@ -979,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)");
@@ -1010,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) {
@@ -1024,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);
@@ -1040,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" },
@@ -1068,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], [
@@ -1093,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)");
@@ -1126,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" },
@@ -1149,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}`);
         }

package/dist/commands/tasks.js

@@ -1,5 +1,5 @@
 import { createClient } from "../client.js";
-import { table, json as outJson, handleHttp } from "../output.js";
+import { table, json as outJson, jsonRequested, handleHttp } from "../output.js";
 export function registerTasks(program) {
     const cmd = program.command("tasks", { hidden: true }).description("Task runs");
     cmd
@@ -18,7 +18,7 @@ export function registerTasks(program) {
             if (opts.space)
                 filters.spaceId = opts.space;
             const result = await client.tasks.list(filters);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             if (result.runs.length === 0)
                 return console.log("  (empty)");
@@ -41,7 +41,7 @@ export function registerTasks(program) {
         const client = createClient();
         try {
             const result = await client.tasks.get(id);
-            if (opts.json)
+            if (jsonRequested(opts))
                 return outJson(result);
             table([result.run], [
                 { key: "id", label: "ID" },

package/dist/output.d.ts

@@ -4,6 +4,9 @@ export declare function table(rows: Row[], columns: {
     label: string;
 }[]): void;
 export declare function json(data: unknown): void;
+export declare function jsonRequested(opts?: {
+    json?: boolean;
+}): boolean;
 export declare function ok(msg: string): void;
 export declare function error(msg: string, detail?: string): never;
 export declare function handleHttp(e: unknown): never;

package/dist/output.js

@@ -35,6 +35,9 @@ export function table(rows, columns) {
 export function json(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+export function jsonRequested(opts) {
+    return Boolean(opts?.json || process.argv.includes("--json"));
+}
 export function ok(msg) {
     console.log(`\n  ✓ ${msg}\n`);
 }

package/dist/space.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function resolveSpace(program: Command): string;

package/dist/space.js

@@ -0,0 +1,14 @@
+import { error } from "./output.js";
+export function resolveSpace(program) {
+    let current = program;
+    while (current) {
+        const opts = current.opts();
+        if (typeof opts.space === "string" && opts.space.trim())
+            return opts.space.trim();
+        current = current.parent ?? null;
+    }
+    const envSpace = process.env.COHUB_SPACE_ID?.trim();
+    if (envSpace)
+        return envSpace;
+    return error("Missing required space", "Add -s, --space <id> or set COHUB_SPACE_ID.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "UNLICENSED",
@@ -15,7 +15,7 @@
   "dependencies": {
     "commander": "^13.1.0",
     "sharp": "^0.34.5",
-    "@neta-art/cohub": "1.15.1"
+    "@neta-art/cohub": "1.16.0"
   },
   "publishConfig": {
     "access": "public"