@neta-art/cohub-cli 1.7.0 → 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], [