@neta-art/cohub-cli 1.20.6 → 2.1.0

package/README.md

@@ -149,6 +149,16 @@ cohub generate "restyle this image" \
   --param size=1024x1024 \
   --json
 
+cohub generate "smoothly transition from the first frame to the last frame" \
+  --model seedance-2-0-fast \
+  --image first_frame=https://example.com/first.png \
+  --image last_frame=https://example.com/last.png
+
+cohub generate "keep the character identity from all reference images" \
+  --model seedance-2-0-fast \
+  --image reference_image=https://example.com/reference-1.png \
+  --image reference_image=https://example.com/reference-2.png
+
 cohub generate "a calm lake" \
   --model <model> \
   --async
@@ -160,10 +170,16 @@ Supported inputs:
 
 ```bash
 --image <path-or-url>
+--image first_frame=<path-or-url>
+--image last_frame=<path-or-url>
+--image reference_image=<path-or-url>
 --video <path-or-url>
+--video reference_video=<path-or-url>
 --audio <path-or-url>
 ```
 
+Role-qualified media values add `meta.role` to that content block. Repeat `--image reference_image=...` for multiple reference images. Seedance role-qualified media should use public URL inputs. Do not mix first/last frame roles with reference roles in one request.
+
 Pass generation parameters with `--param key=value` or `--parameters '<json>'`.
 
 ## Files
@@ -191,7 +207,7 @@ cohub works get <workId> --json
 cohub -s <spaceId> works publish demo --file dist/index.html
 cohub -s <spaceId> works publish site --dir dist
 cohub -s <spaceId> works publish app --port 3000
-cohub works update <workId> --publish-version
+cohub works publish-version <workId>
 cohub works versions <workId> --json
 cohub works rm <workId> --yes
 ```

package/dist/commands/generations.js

@@ -4,6 +4,14 @@ import { GenerationPolicyError, assertGenerationRequestAllowedByPolicy, parseGen
 import { createClient } from "../client.js";
 import { resolveSpace } from "../space.js";
 import { json as outJson, jsonRequested, ok, error, handleHttp, spinner } from "../output.js";
+const frameMediaRoles = new Set(["first_frame", "last_frame"]);
+const referenceMediaRoles = new Set(["reference_image", "reference_video"]);
+const rolesByMediaType = {
+    image: new Set([...frameMediaRoles, "reference_image"]),
+    video: new Set(["reference_video"]),
+    audio: new Set(),
+};
+const mediaRoles = new Set([...frameMediaRoles, ...referenceMediaRoles]);
 const mimeByExt = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -45,12 +53,47 @@ function parseParams(param, parameters) {
     }
     return Object.keys(result).length > 0 ? result : undefined;
 }
-async function contentFromPathOrUrl(type, value) {
-    if (/^https?:\/\//.test(value))
-        return { type, source: { type: "url", url: value } };
+async function pathExists(path) {
+    return Boolean(await stat(path).catch(() => null));
+}
+async function parseMediaInput(type, rawValue) {
+    const separator = rawValue.indexOf("=");
+    if (separator <= 0)
+        return { value: rawValue };
+    const role = rawValue.slice(0, separator).trim();
+    if (!mediaRoles.has(role))
+        return { value: rawValue };
+    if (await pathExists(rawValue))
+        return { value: rawValue };
+    if (!rolesByMediaType[type].has(role)) {
+        return error("Invalid media role", `${role} cannot be used with --${type}`);
+    }
+    const value = rawValue.slice(separator + 1).trim();
+    if (!value)
+        return error("Invalid media input", `--${type} ${role}= requires a path or URL`);
+    return { value, role };
+}
+async function contentFromPathOrUrl(type, rawValue) {
+    const { value, role } = await parseMediaInput(type, rawValue);
+    const meta = role ? { role } : undefined;
+    if (/^https?:\/\//.test(value)) {
+        return { type, source: { type: "url", url: value }, ...(meta ? { meta } : {}) };
+    }
     const data = await readFile(value);
     const mediaType = mimeByExt[extname(value).toLowerCase()] ?? "application/octet-stream";
-    return { type, source: { type: "base64", mediaType, data: data.toString("base64") } };
+    return {
+        type,
+        source: { type: "base64", mediaType, data: data.toString("base64") },
+        ...(meta ? { meta } : {}),
+    };
+}
+function validateMediaRoleModes(content) {
+    const roles = content.map(metaRole).filter((role) => Boolean(role));
+    const hasFrameRole = roles.some((role) => frameMediaRoles.has(role));
+    const hasReferenceRole = roles.some((role) => referenceMediaRoles.has(role));
+    if (hasFrameRole && hasReferenceRole) {
+        error("Invalid media role mix", "Use first_frame/last_frame or reference_image/reference_video, not both.");
+    }
 }
 async function saveOutputs(output, outputPath) {
     const outputs = output.filter((block) => block.type === "text" || block.type === "image" || block.type === "video" || block.type === "audio");
@@ -212,8 +255,8 @@ export function registerGenerations(program) {
         .description("Generate multimodal outputs")
         .argument("<prompt>", "Prompt text")
         .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("--image <path-or-url>", "Image input file path or URL; prefix with first_frame=, last_frame=, or reference_image= when needed; repeatable", collect, [])
+        .option("--video <path-or-url>", "Video input file path or URL; prefix with reference_video= when needed; 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")
@@ -228,6 +271,8 @@ Examples:
   cohub models ls --model-type multimodal
   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 "Smooth transition" -m seedance-2-0-fast --image first_frame=https://example.com/first.png --image last_frame=https://example.com/last.png
+  cohub -s <space-id> generate "Use these references" -m seedance-2-0-fast --image reference_image=https://example.com/a.png --image reference_image=https://example.com/b.png
   cohub -s <space-id> generate "A calm lake" -m <model> --async
 `)
         .action(async (prompt, opts) => {
@@ -237,6 +282,7 @@ Examples:
             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))));
+            validateMediaRoleModes(content);
             const parameters = parseParams(opts.param, opts.parameters);
             try {
                 assertGenerationRequestAllowedByPolicy({

package/dist/commands/models.js

@@ -17,6 +17,7 @@ function printSection(title, lines) {
 }
 function formatContentSpec(spec) {
     const details = [];
+    const roles = spec.roles;
     details.push(spec.required === false ? "optional" : "required");
     if (typeof spec.min === "number")
         details.push(`min ${spec.min}`);
@@ -24,6 +25,8 @@ function formatContentSpec(spec) {
         details.push(`max ${spec.max}`);
     if (spec.sources?.length)
         details.push(`sources: ${spec.sources.join(", ")}`);
+    if (roles?.length)
+        details.push(`roles: ${roles.join(", ")}`);
     if (spec.merge)
         details.push(`merge: ${spec.merge}`);
     if (spec.description)

package/dist/commands/run.js

@@ -14,7 +14,7 @@ function shellJoin(values) {
 }
 function topLevelRunIndex(argv) {
     for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
+        const token = argv[index] ?? "";
         if (token === "--")
             return -1;
         if (token === "-s" || token === "--space") {
@@ -31,7 +31,7 @@ function topLevelRunIndex(argv) {
 }
 function parseSpaceId(tokens) {
     for (let index = 0; index < tokens.length; index += 1) {
-        const token = tokens[index];
+        const token = tokens[index] ?? "";
         if (token === "-s" || token === "--space") {
             const value = tokens[index + 1];
             if (!value)
@@ -55,7 +55,7 @@ function parseRunCliOptions(argv) {
     let commandOption = null;
     let positionalTokens = [];
     for (let index = 0; index < afterRun.length; index += 1) {
-        const token = afterRun[index];
+        const token = afterRun[index] ?? "";
         if (token === "-h" || token === "--help") {
             printRunHelp();
             process.exit(0);

package/dist/commands/space-commerce.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerSpaceCommerce(spacesCmd: Command): void;

package/dist/commands/space-commerce.js

@@ -0,0 +1,453 @@
+import { createClient } from "../client.js";
+import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
+import { resolveSpace } from "../space.js";
+const PRODUCT_STATUSES = ["draft", "active"];
+const PRODUCT_UPDATE_STATUSES = ["draft", "active", "archived"];
+const PRODUCT_VISIBILITIES = ["public", "private"];
+const BENEFIT_STATUSES = ["active", "archived"];
+function requireText(value, label, flag) {
+    const text = value?.trim();
+    if (text)
+        return text;
+    return error(`Missing ${label}`, `Pass ${flag}.`);
+}
+function parseChoice(value, label, choices) {
+    if (value === undefined)
+        return undefined;
+    if (choices.includes(value))
+        return value;
+    return error(`Invalid ${label}`, `Use one of: ${choices.join(", ")}.`);
+}
+function parseInteger(value, label, options) {
+    if (value === undefined)
+        return options.fallback;
+    if (!/^-?\d+$/.test(value.trim()))
+        return error(`Invalid ${label}`, `${label} must be an integer.`);
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(parsed))
+        return error(`Invalid ${label}`, `${label} must be a safe integer.`);
+    if (options.min !== undefined && parsed < options.min)
+        return error(`Invalid ${label}`, `${label} must be at least ${options.min}.`);
+    if (options.max !== undefined && parsed > options.max)
+        return error(`Invalid ${label}`, `${label} must be at most ${options.max}.`);
+    return parsed;
+}
+function parseAmountUsd(value) {
+    const text = requireText(value, "amount", "--amount-usd <amount>");
+    if (!/^(?:\d+|\d+\.\d{1,2}|\.\d{1,2})$/.test(text)) {
+        return error("Invalid amount", "--amount-usd must be a non-negative USD amount with at most 2 decimals.");
+    }
+    const amount = Number(text);
+    if (!Number.isFinite(amount))
+        return error("Invalid amount", "--amount-usd must be a finite USD amount.");
+    return amount;
+}
+function parseMetadataJson(value) {
+    if (value === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return error("Invalid metadata", "--metadata-json must be a JSON object.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return error("Invalid metadata", "--metadata-json must be a JSON object.");
+    }
+    const metadata = {};
+    for (const [key, item] of Object.entries(parsed)) {
+        if (typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean") {
+            return error("Invalid metadata", `Metadata value for "${key}" must be string, number, or boolean.`);
+        }
+        if (typeof item === "number" && !Number.isFinite(item)) {
+            return error("Invalid metadata", `Metadata value for "${key}" must be a finite number.`);
+        }
+        metadata[key] = item;
+    }
+    return metadata;
+}
+function compact(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function formatUsd(amount) {
+    return `$${amount.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+function formatMinorUsd(amountMinor) {
+    return formatUsd(amountMinor / 100);
+}
+function printProducts(products) {
+    table(products.map((product) => ({
+        key: product.key,
+        name: product.name,
+        status: product.status,
+        visibility: product.visibility,
+        price: formatUsd(product.pricing.amountUsd),
+    })), [
+        { key: "key", label: "Key" },
+        { key: "name", label: "Name" },
+        { key: "status", label: "Status" },
+        { key: "visibility", label: "Visibility" },
+        { key: "price", label: "Price" },
+    ]);
+}
+function printBenefits(benefits) {
+    table(benefits.map((benefit) => ({
+        key: benefit.key,
+        name: benefit.name,
+        status: benefit.status,
+        description: benefit.description ?? "",
+    })), [
+        { key: "key", label: "Key" },
+        { key: "name", label: "Name" },
+        { key: "status", label: "Status" },
+        { key: "description", label: "Description" },
+    ]);
+}
+function printOrders(orders) {
+    table(orders.map((order) => ({
+        id: order.id,
+        product: order.productKeySnapshot,
+        status: order.status,
+        amount: formatMinorUsd(order.amountSnapshot),
+        created: order.createdAt,
+    })), [
+        { key: "id", label: "ID" },
+        { key: "product", label: "Product" },
+        { key: "status", label: "Status" },
+        { key: "amount", label: "Amount" },
+        { key: "created", label: "Created" },
+    ]);
+}
+async function confirmDanger(opts, detail) {
+    if (opts.yes)
+        return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return error("Confirmation required", `Pass --yes to ${detail}.`);
+    process.stdout.write(`${detail[0]?.toUpperCase() ?? "C"}${detail.slice(1)}? [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");
+}
+function commerceClient(spacesCmd) {
+    const spaceId = resolveSpace(spacesCmd);
+    return { spaceId, commerce: createClient().space(spaceId).commerce };
+}
+export function registerSpaceCommerce(spacesCmd) {
+    const commerceCmd = spacesCmd
+        .command("commerce")
+        .description("Manage space commerce")
+        .addHelpText("after", `
+Examples:
+  cohub -s <space-id> spaces commerce setup
+  cohub -s <space-id> spaces commerce products list
+  COHUB_SPACE_ID=<space-id> cohub spaces commerce orders list --limit 10
+`);
+    commerceCmd
+        .command("setup")
+        .description("Initialize commerce for the target space")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.setup();
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Commerce initialized: ${result.businessKey}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    const productsCmd = commerceCmd
+        .command("products")
+        .description("Manage products")
+        .addHelpText("after", `
+Examples:
+  cohub -s <space-id> spaces commerce products list
+  cohub -s <space-id> spaces commerce products create --name "Pro Pack" --amount-usd 9.99
+`);
+    productsCmd
+        .command("list")
+        .description("List products")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.listProducts();
+            if (jsonRequested(opts))
+                return outJson(result);
+            printProducts(result.products);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    productsCmd
+        .command("create")
+        .description("Create a product")
+        .option("--product-key <key>", "Product key override")
+        .option("--name <name>", "Product name")
+        .option("--amount-usd <amount>", "One-time price in USD")
+        .option("--description <text>", "Product description")
+        .option("--status <status>", "Product status: draft, active")
+        .option("--visibility <visibility>", "Product visibility: public, private")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const input = {
+            key: opts.productKey?.trim() || undefined,
+            name: requireText(opts.name, "name", "--name <name>"),
+            description: opts.description,
+            amountUsd: parseAmountUsd(opts.amountUsd),
+            status: parseChoice(opts.status, "status", PRODUCT_STATUSES),
+            visibility: parseChoice(opts.visibility, "visibility", PRODUCT_VISIBILITIES),
+        };
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.createProduct(input);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Product created: ${result.product.key}`);
+            printProducts([result.product]);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    productsCmd
+        .command("update")
+        .description("Update a product")
+        .option("--product-key <key>", "Product key")
+        .option("--name <name>", "Product name")
+        .option("--description <text>", "Product description")
+        .option("--clear-description", "Clear the product description")
+        .option("--status <status>", "Product status: draft, active, archived")
+        .option("--visibility <visibility>", "Product visibility: public, private")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        if (opts.description !== undefined && opts.clearDescription)
+            return error("Conflicting description", "Use either --description or --clear-description.");
+        const productKey = requireText(opts.productKey, "product key", "--product-key <key>");
+        const input = compact({
+            name: opts.name,
+            description: opts.clearDescription ? null : opts.description,
+            status: parseChoice(opts.status, "status", PRODUCT_UPDATE_STATUSES),
+            visibility: parseChoice(opts.visibility, "visibility", PRODUCT_VISIBILITIES),
+        });
+        if (Object.keys(input).length === 0)
+            return error("Nothing to update", "Pass --name, --description, --clear-description, --status, or --visibility.");
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.updateProduct(productKey, input);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Product updated: ${result.product.key}`);
+            printProducts([result.product]);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    productsCmd
+        .command("archive")
+        .description("Archive a product")
+        .option("--product-key <key>", "Product key")
+        .option("-y, --yes", "Confirm archive")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const productKey = requireText(opts.productKey, "product key", "--product-key <key>");
+        await confirmDanger(opts, `archive product "${productKey}"`);
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.updateProduct(productKey, { status: "archived" });
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Product archived: ${result.product.key}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    const benefitsCmd = commerceCmd
+        .command("benefits")
+        .description("Manage benefits")
+        .addHelpText("after", `
+Examples:
+  cohub -s <space-id> spaces commerce benefits list
+  cohub -s <space-id> spaces commerce benefits create --name "Premium Export" --metadata-json '{"limit":100}'
+`);
+    benefitsCmd
+        .command("list")
+        .description("List benefits")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.listBenefits();
+            if (jsonRequested(opts))
+                return outJson(result);
+            printBenefits(result.benefits);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    benefitsCmd
+        .command("create")
+        .description("Create a benefit")
+        .option("--benefit-key <key>", "Benefit key override")
+        .option("--name <name>", "Benefit name")
+        .option("--description <text>", "Benefit description")
+        .option("--metadata-json <json>", "Benefit metadata JSON object")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const input = {
+            key: opts.benefitKey?.trim() || undefined,
+            name: requireText(opts.name, "name", "--name <name>"),
+            description: opts.description,
+            metadata: parseMetadataJson(opts.metadataJson),
+        };
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.createBenefit(input);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Benefit created: ${result.benefit.key}`);
+            printBenefits([result.benefit]);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    benefitsCmd
+        .command("update")
+        .description("Update a benefit")
+        .option("--benefit-key <key>", "Benefit key")
+        .option("--name <name>", "Benefit name")
+        .option("--description <text>", "Benefit description")
+        .option("--clear-description", "Clear the benefit description")
+        .option("--status <status>", "Benefit status: active, archived")
+        .option("--metadata-json <json>", "Replace metadata with a JSON object")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        if (opts.description !== undefined && opts.clearDescription)
+            return error("Conflicting description", "Use either --description or --clear-description.");
+        const benefitKey = requireText(opts.benefitKey, "benefit key", "--benefit-key <key>");
+        const input = compact({
+            name: opts.name,
+            description: opts.clearDescription ? null : opts.description,
+            status: parseChoice(opts.status, "status", BENEFIT_STATUSES),
+            metadata: parseMetadataJson(opts.metadataJson),
+        });
+        if (Object.keys(input).length === 0)
+            return error("Nothing to update", "Pass --name, --description, --clear-description, --status, or --metadata-json.");
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.updateBenefit(benefitKey, input);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Benefit updated: ${result.benefit.key}`);
+            printBenefits([result.benefit]);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    benefitsCmd
+        .command("archive")
+        .description("Archive a benefit")
+        .option("--benefit-key <key>", "Benefit key")
+        .option("-y, --yes", "Confirm archive")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const benefitKey = requireText(opts.benefitKey, "benefit key", "--benefit-key <key>");
+        await confirmDanger(opts, `archive benefit "${benefitKey}"`);
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.updateBenefit(benefitKey, { status: "archived" });
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Benefit archived: ${result.benefit.key}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    commerceCmd
+        .command("bind")
+        .description("Bind a benefit to a product")
+        .option("--product-key <key>", "Product key")
+        .option("--benefit-key <key>", "Benefit key")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const input = {
+            productKey: requireText(opts.productKey, "product key", "--product-key <key>"),
+            benefitKey: requireText(opts.benefitKey, "benefit key", "--benefit-key <key>"),
+        };
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.bindProductBenefit(input);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Benefit bound: ${input.benefitKey} -> ${input.productKey}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    commerceCmd
+        .command("unbind")
+        .description("Unbind a benefit from a product")
+        .option("--product-key <key>", "Product key")
+        .option("--benefit-key <key>", "Benefit key")
+        .option("-y, --yes", "Confirm unbind")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const input = {
+            productKey: requireText(opts.productKey, "product key", "--product-key <key>"),
+            benefitKey: requireText(opts.benefitKey, "benefit key", "--benefit-key <key>"),
+        };
+        await confirmDanger(opts, `unbind benefit "${input.benefitKey}" from product "${input.productKey}"`);
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.unbindProductBenefit(input);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Benefit unbound: ${input.benefitKey} -> ${input.productKey}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    const ordersCmd = commerceCmd
+        .command("orders")
+        .description("Manage orders");
+    ordersCmd
+        .command("list")
+        .description("List recent orders")
+        .option("--page <page>", "Page number")
+        .option("--limit <limit>", "Page size, max 50")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const { commerce } = commerceClient(spacesCmd);
+        try {
+            const result = await commerce.listOrders({
+                page: parseInteger(opts.page, "page", { fallback: 1, min: 1 }),
+                limit: parseInteger(opts.limit, "limit", { fallback: 20, min: 1, max: 50 }),
+            });
+            if (jsonRequested(opts))
+                return outJson(result);
+            printOrders(result.orders);
+            if (result.pagination.hasMore)
+                console.log(`\nNext page: ${result.pagination.nextPage}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+}

package/dist/commands/spaces.js

@@ -7,6 +7,7 @@ import { uploadAvatarAsset, uploadChatImageAsset } from "../avatar.js";
 import { createClient } from "../client.js";
 import { table, json as outJson, jsonRequested, ok, error, handleHttp } from "../output.js";
 import { resolveSpace } from "../space.js";
+import { registerSpaceCommerce } from "./space-commerce.js";
 const cliEnv = resolveCohubEnvironment();
 const defaultIdleTtlSeconds = cliEnv === "prod" ? 12 * 60 * 60 : 10 * 60;
 const SPACE_ROLES = ["host", "builder", "guest"];
@@ -478,6 +479,8 @@ export function registerSpaces(program) {
     registerMods(spacesCmd);
     // ── spaces labels ──
     registerLabels(spacesCmd);
+    // ── spaces commerce ──
+    registerSpaceCommerce(spacesCmd);
     // ── spaces usage ──
     spacesCmd
         .command("usage [days]")

package/dist/commands/work-commerce.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerWorkCommerce(worksCmd: Command): void;

package/dist/commands/work-commerce.js

@@ -0,0 +1,185 @@
+import { createClient } from "../client.js";
+import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
+function collectOption(value, previous = []) {
+    return [...previous, value];
+}
+function requireText(value, label, flag) {
+    const text = value?.trim();
+    if (text)
+        return text;
+    return error(`Missing ${label}`, `Pass ${flag}.`);
+}
+function requireList(values, label, flag) {
+    const items = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
+    if (items.length > 0)
+        return items;
+    return error(`Missing ${label}`, `Pass ${flag}.`);
+}
+function formatUsd(amount) {
+    return `$${amount.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+function formatMinorUsd(amountMinor) {
+    return formatUsd(amountMinor / 100);
+}
+function printProducts(products) {
+    table(products.map((product) => ({
+        key: product.key,
+        name: product.name,
+        status: product.status,
+        visibility: product.visibility,
+        price: formatUsd(product.pricing.amountUsd),
+    })), [
+        { key: "key", label: "Key" },
+        { key: "name", label: "Name" },
+        { key: "status", label: "Status" },
+        { key: "visibility", label: "Visibility" },
+        { key: "price", label: "Price" },
+    ]);
+}
+function printEntitlements(entitlements) {
+    table(entitlements.map((item) => ({
+        benefitKey: item.benefitKey,
+        enabled: item.enabled ? "yes" : "no",
+        reason: item.reason,
+        metadata: item.metadata ? JSON.stringify(item.metadata) : "",
+    })), [
+        { key: "benefitKey", label: "Benefit" },
+        { key: "enabled", label: "Enabled" },
+        { key: "reason", label: "Reason" },
+        { key: "metadata", label: "Metadata" },
+    ]);
+}
+function printOrder(order) {
+    table([{
+            id: order.id,
+            product: order.productKeySnapshot,
+            status: order.status,
+            amount: formatMinorUsd(order.amountSnapshot),
+            paid: formatMinorUsd(order.paidAmountSnapshot),
+            created: order.createdAt,
+            paidAt: order.paidAt ?? "",
+        }], [
+        { key: "id", label: "ID" },
+        { key: "product", label: "Product" },
+        { key: "status", label: "Status" },
+        { key: "amount", label: "Amount" },
+        { key: "paid", label: "Paid" },
+        { key: "created", label: "Created" },
+        { key: "paidAt", label: "Paid At" },
+    ]);
+}
+export function registerWorkCommerce(worksCmd) {
+    const commerceCmd = worksCmd
+        .command("commerce")
+        .description("Debug work commerce")
+        .addHelpText("after", `
+Examples:
+  cohub works commerce products resolve --work-id <work-id> --product-key pro_pack
+  cohub works commerce entitlements check --work-id <work-id> --benefit-key premium_export
+`);
+    const productsCmd = commerceCmd
+        .command("products")
+        .description("Debug commerce products");
+    productsCmd
+        .command("resolve")
+        .description("Resolve public products for a work")
+        .option("--work-id <id>", "Work ID")
+        .option("--product-key <key>", "Product key", collectOption)
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const productKeys = requireList(opts.productKey, "product key", "--product-key <key>");
+        const client = createClient();
+        try {
+            const result = await client.workCommerce.resolveProducts(workId, { productKeys });
+            if (jsonRequested(opts))
+                return outJson(result);
+            printProducts(result.products);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    const entitlementsCmd = commerceCmd
+        .command("entitlements")
+        .description("Debug commerce entitlements");
+    entitlementsCmd
+        .command("check")
+        .description("Check viewer entitlements for a work")
+        .option("--work-id <id>", "Work ID")
+        .option("--benefit-key <key>", "Benefit key", collectOption)
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const benefitKeys = requireList(opts.benefitKey, "benefit key", "--benefit-key <key>");
+        const client = createClient();
+        try {
+            const result = await client.workCommerce.checkEntitlements(workId, { benefitKeys });
+            if (jsonRequested(opts))
+                return outJson(result);
+            printEntitlements(result.entitlements);
+            console.log(`\nChecked at: ${result.checkedAt}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    commerceCmd
+        .command("purchase")
+        .description("Create a work purchase checkout")
+        .option("--work-id <id>", "Work ID")
+        .option("--product-key <key>", "Product key")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const productKey = requireText(opts.productKey, "product key", "--product-key <key>");
+        const client = createClient();
+        try {
+            const result = await client.workCommerce.purchase(workId, { productKey });
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Checkout created: ${result.checkout.orderId}`);
+            table([{
+                    orderId: result.checkout.orderId,
+                    productKey: result.checkout.productKey,
+                    usable: result.checkout.checkoutUsable ? "yes" : "no",
+                    status: result.checkout.status ?? "",
+                    checkoutUrl: result.checkout.checkoutUrl ?? "",
+                    message: result.checkout.message ?? "",
+                }], [
+                { key: "orderId", label: "Order" },
+                { key: "productKey", label: "Product" },
+                { key: "usable", label: "Usable" },
+                { key: "status", label: "Status" },
+                { key: "checkoutUrl", label: "Checkout URL" },
+                { key: "message", label: "Message" },
+            ]);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    const ordersCmd = commerceCmd
+        .command("orders")
+        .description("Debug commerce orders");
+    ordersCmd
+        .command("get")
+        .description("Show a work commerce order")
+        .option("--work-id <id>", "Work ID")
+        .option("--order-id <id>", "Order ID")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const orderId = requireText(opts.orderId, "order ID", "--order-id <id>");
+        const client = createClient();
+        try {
+            const result = await client.workCommerce.getOrder(workId, orderId);
+            if (jsonRequested(opts))
+                return outJson(result);
+            printOrder(result.order);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+}

package/dist/commands/works.js

@@ -1,7 +1,10 @@
+import { HttpError } from "@neta-art/cohub";
 import { createClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
-const WORK_STATUSES = ["draft", "published", "disabled"];
+import { registerWorkCommerce } from "./work-commerce.js";
+const WORK_STATUSES = ["published", "disabled"];
+const WORK_VISIBILITIES = ["public", "space"];
 const collectOption = (value, previous = []) => [...previous, value];
 function parseChoice(value, name, choices) {
     if (choices.includes(value))
@@ -54,16 +57,20 @@ function resolveTarget(opts) {
     return targets[0] ?? null;
 }
 function resolveStatus(opts) {
-    const values = [opts.status, opts.draft ? "draft" : undefined, opts.disabled ? "disabled" : undefined].filter(Boolean);
+    const values = [opts.status, opts.disabled ? "disabled" : undefined].filter(Boolean);
     if (values.length > 1)
-        return error("Conflicting status", "Use only one of --status, --draft, or --disabled");
+        return error("Conflicting status", "Use only one of --status or --disabled");
     return values[0] ? parseChoice(values[0], "status", WORK_STATUSES) : "published";
 }
+function resolveVisibility(value) {
+    return value ? parseChoice(value, "visibility", WORK_VISIBILITIES) : undefined;
+}
 function printWork(work) {
     table([work], [
         { key: "id", label: "ID" },
         { key: "slug", label: "Slug" },
         { key: "status", label: "Status" },
+        { key: "visibility", label: "Visibility" },
         { key: "targetType", label: "Target" },
         { key: "targetRef", label: "Ref" },
         { key: "latestVersion", label: "Version" },
@@ -93,6 +100,19 @@ async function confirmDelete(opts) {
     if (answer !== "y" && answer !== "yes")
         return error("Cancelled");
 }
+async function publishWorkVersion(id, opts) {
+    const client = createClient();
+    try {
+        const result = await client.works.publishVersion(id);
+        if (jsonRequested(opts))
+            return outJson(result);
+        ok(`Work version updated: v${result.version.version}`);
+        printWork(result.work);
+    }
+    catch (e) {
+        handleHttp(e);
+    }
+}
 export function registerWorks(program) {
     const worksCmd = program.command("works").description("Work management");
     worksCmd
@@ -111,6 +131,7 @@ export function registerWorks(program) {
                 { key: "id", label: "ID" },
                 { key: "slug", label: "Slug" },
                 { key: "status", label: "Status" },
+                { key: "visibility", label: "Visibility" },
                 { key: "targetType", label: "Target" },
                 { key: "targetRef", label: "Ref" },
                 { key: "latestVersion", label: "Version" },
@@ -167,9 +188,9 @@ export function registerWorks(program) {
         .option("--file <path>", "Publish a HTML file")
         .option("--dir <path>", "Publish a directory site")
         .option("--port <port>", "Publish a public sandbox port")
-        .option("--draft", "Create as draft")
         .option("--disabled", "Create as disabled")
-        .option("--status <status>", "Work status: draft, published, disabled")
+        .option("--status <status>", "Work status: published, disabled")
+        .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
         .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--meta <json>", "Work metadata as a JSON object")
@@ -194,6 +215,7 @@ export function registerWorks(program) {
             spaceId,
             slug,
             status,
+            visibility: resolveVisibility(opts.visibility),
             targetType: target.targetType,
             targetRef: target.targetRef,
             workScopes: opts.workScope,
@@ -208,20 +230,44 @@ export function registerWorks(program) {
             printWork(result.work);
         }
         catch (e) {
-            handleHttp(e);
+            if (!(e instanceof HttpError) || e.status !== 409)
+                handleHttp(e);
+            try {
+                const { works } = await client.works.listBySpace(spaceId);
+                const existingWork = works.find((work) => work.slug === slug);
+                if (!existingWork)
+                    return handleHttp(e);
+                const { work } = await client.works.update(existingWork.id, {
+                    status: status === "published" && existingWork.status !== "published" ? existingWork.status : status,
+                    visibility: resolveVisibility(opts.visibility),
+                    targetType: target.targetType,
+                    targetRef: target.targetRef,
+                    workScopes: opts.workScope,
+                    allowedViewerScopes: opts.viewerScope,
+                    meta,
+                });
+                const publishedVersion = status === "published" ? await client.works.publishVersion(work.id) : null;
+                const result = publishedVersion ?? { work };
+                if (jsonRequested(opts))
+                    return outJson(result);
+                ok(status === "published" && publishedVersion ? `Work version updated: v${publishedVersion.version.version}` : `Work updated: ${work.id}`);
+                printWork(result.work);
+            }
+            catch (fallbackError) {
+                handleHttp(fallbackError);
+            }
         }
     });
     worksCmd
         .command("update <id>")
-        .description("Update work settings or publish a new version")
+        .description("Update work settings")
         .option("--slug <slug>", "New work slug")
         .option("--file <path>", "Use a HTML file target")
         .option("--dir <path>", "Use a directory site target")
         .option("--port <port>", "Use a public sandbox port target")
-        .option("--draft", "Set status to draft")
         .option("--disabled", "Set status to disabled")
-        .option("--status <status>", "Work status: draft, published, disabled")
-        .option("--publish-version", "Force publishing a new version")
+        .option("--status <status>", "Work status: published, disabled")
+        .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
         .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--clear-work-scopes", "Clear work runtime scopes")
@@ -257,29 +303,45 @@ export function registerWorks(program) {
                 showCohubBar: opts.showCohubBar,
             });
         }
+        const nextStatus = opts.status || opts.disabled ? resolveStatus(opts) : undefined;
+        const currentWork = nextStatus === "published" ? (await client.works.get(id)).work : null;
         const input = compactObject({
             slug: opts.slug,
-            status: opts.status || opts.draft || opts.disabled ? resolveStatus(opts) : undefined,
+            status: nextStatus === "published" && currentWork?.status !== "published" ? currentWork?.status : nextStatus,
+            visibility: resolveVisibility(opts.visibility),
             targetType: target?.targetType,
             targetRef: target?.targetRef,
-            publishVersion: opts.publishVersion || undefined,
             workScopes: opts.clearWorkScopes ? [] : opts.workScope?.length ? opts.workScope : undefined,
             allowedViewerScopes: opts.clearViewerScopes ? [] : opts.viewerScope?.length ? opts.viewerScope : undefined,
             meta,
         });
         if (Object.keys(input).length === 0)
-            return error("Nothing to update", "Pass --slug, --file, --dir, --port, --status, --publish-version, --work-scope, --viewer-scope, --clear-work-scopes, --clear-viewer-scopes, --meta, --hide-cohub-bar, or --show-cohub-bar.");
+            return error("Nothing to update", "Pass --slug, --file, --dir, --port, --status, --visibility, --work-scope, --viewer-scope, --clear-work-scopes, --clear-viewer-scopes, --meta, --hide-cohub-bar, or --show-cohub-bar.");
         try {
-            const result = await client.works.update(id, input);
+            const updated = await client.works.update(id, input);
+            const publishedVersion = nextStatus === "published" && currentWork?.status !== "published"
+                ? await client.works.publishVersion(updated.work.id)
+                : null;
+            const result = publishedVersion ?? updated;
             if (jsonRequested(opts))
                 return outJson(result);
-            ok("Work updated");
+            ok(publishedVersion ? `Work published: v${publishedVersion.version.version}` : "Work updated");
             printWork(result.work);
         }
         catch (e) {
             handleHttp(e);
         }
     });
+    worksCmd
+        .command("publish-version <id>")
+        .description("Publish or update the current work version")
+        .option("--json", "Output as JSON")
+        .action(publishWorkVersion);
+    worksCmd
+        .command("release <id>", { hidden: true })
+        .description("Deprecated alias for publish-version")
+        .option("--json", "Output as JSON")
+        .action(publishWorkVersion);
     worksCmd
         .command("versions <id>")
         .description("List work versions")
@@ -293,16 +355,16 @@ export function registerWorks(program) {
             table(result.versions, [
                 { key: "version", label: "Version" },
                 { key: "id", label: "ID" },
-                { key: "status", label: "Status" },
                 { key: "targetType", label: "Target" },
                 { key: "targetRef", label: "Ref" },
-                { key: "publishedAt", label: "Published" },
+                { key: "createdAt", label: "Created" },
             ]);
         }
         catch (e) {
             handleHttp(e);
         }
     });
+    registerWorkCommerce(worksCmd);
     worksCmd
         .command("rm <id>")
         .alias("delete")

package/dist/index.js

@@ -44,6 +44,7 @@ Common commands:
   cohub -s <space-id> spaces sessions turns ls <session-id>
   cohub -s <space-id> spaces files ls
   cohub -s <space-id> works publish demo --file dist/index.html
+  cohub -s <space-id> spaces commerce products list
   cohub models ls
   cohub models ls --model-type multimodal
   cohub generate "A calm lake at sunrise" --model <model> --output lake.png

package/dist/output.js

@@ -85,15 +85,28 @@ function fetchFailureDetail(e) {
         ? `Network request failed (${parts.join(" · ")}). Check DNS/proxy/firewall settings and try again.`
         : "Network request failed. Check DNS/proxy/firewall settings and try again.";
 }
+function errorPresentationFromHttpError(e) {
+    const httpError = e;
+    if (httpError.code === "space_commerce_not_initialized") {
+        return {
+            message: "space commerce is not initialized",
+            detail: "run `cohub -s <space-id> spaces commerce setup` first",
+        };
+    }
+    return null;
+}
 export function handleHttp(e) {
     if (e instanceof Error && e.name === "AuthRequiredError") {
         return error("not authenticated", "run `cohub auth login`");
     }
     const status = e.status;
     const body = e.body;
-    const message = errorMessageFromBody(body) ?? (e instanceof Error ? e.message : String(e));
+    const presentation = errorPresentationFromHttpError(e);
+    const message = presentation?.message ?? errorMessageFromBody(body) ?? (e instanceof Error ? e.message : String(e));
     const fetchDetail = fetchFailureDetail(e);
     const detailParts = [];
+    if (presentation?.detail)
+        detailParts.push(presentation.detail);
     if (process.env.COHUB_DEBUG_ERRORS) {
         if (status)
             detailParts.push(`HTTP ${status}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "1.20.6",
+  "version": "2.1.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "UNLICENSED",
@@ -13,10 +13,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@neta-art/generation": "^0.1.9",
+    "@neta-art/generation": "^0.1.10",
     "commander": "^14.0.3",
     "sharp": "^0.34.5",
-    "@neta-art/cohub": "1.34.0"
+    "@neta-art/cohub": "2.1.0"
   },
   "publishConfig": {
     "access": "public"