@miosa/cli 1.1.18 → 1.1.20

package/dist/commands/templates.js

@@ -5,7 +5,6 @@ import { MiosaClient } from "../client.js";
 import { renderTable } from "../ui/table.js";
 import { spin } from "../ui/spinner.js";
 import { handleError, isJsonMode, printJson } from "./util.js";
-import { ApiResponseError, UserError } from "../errors.js";
 function productTemplates(raw) {
     const rows = Array.isArray(raw["data"])
         ? raw["data"]
@@ -36,7 +35,7 @@ function fmtTemplateState(state) {
         return chalk.dim("-");
     if (state === "ready" || state === "active")
         return chalk.green(state);
-    if (state === "building" || state === "pending" || state === "draft")
+    if (state === "building" || state === "pending")
         return chalk.yellow(state);
     if (state === "failed" || state === "error")
         return chalk.red(state);
@@ -46,190 +45,77 @@ function templateState(template) {
     return template.state ?? template.status;
 }
 function templateImage(template) {
-    return template.image ?? template.image_id ?? undefined;
+    return template.image ?? template.image_id;
 }
 function templateCreatedAt(template) {
     return template.created_at ?? template.inserted_at;
 }
-/** A tenant-owned template, as opposed to a platform built-in. */
-function isCustom(template) {
-    if (typeof template.built_in === "boolean")
-        return !template.built_in;
-    // Older payloads without `built_in`: a custom row is the only kind with a
-    // UUID id and the "custom" category.
-    return template.category === "custom" || isUuid(template.id);
-}
-function isUuid(value) {
-    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
-}
-/**
- * A definitive answer to "can I boot a sandbox from this right now?".
- *
- * A template row exists the moment `POST /api/v1/sandbox-templates` returns
- * 201, but it has no bootable image until a build reaches "ready". Reporting
- * the row's mere existence as readiness is what left the customer unable to
- * tell whether his template had been created (2026-08-26 live customer call).
- */
-function usability(template, builds) {
+function templatePresence(template) {
     const state = templateState(template);
     const image = templateImage(template);
-    if (state === "ready" || state === "active") {
-        return image
-            ? { usable: true, reason: `build complete, image ${image}` }
-            : {
-                usable: false,
-                reason: "state is ready but no image was reported - contact support",
-            };
-    }
-    if (state === "archived") {
-        return { usable: false, reason: "archived" };
+    if (image) {
+        return { presence: "present", why: `image ${image} is recorded on the template` };
     }
-    const active = builds?.find((build) => [
-        "queued",
-        "building",
-        "certifying",
-        "snapshotting",
-        "running",
-        "pending",
-    ].includes(build.state ?? ""));
-    if (active) {
-        return {
-            usable: false,
-            reason: `build ${shortId(active.id)} is ${active.state} - not finished yet`,
-        };
+    // A draft or failed build has no image BY DEFINITION - that is a confirmed
+    // absence, not a gap in our knowledge.
+    if (state === "draft" || state === "failed" || state === "error") {
+        return { presence: "absent", why: `template is ${state}, so no image was ever published` };
     }
-    // A failed build explains the template better than the template's own status
-    // does, and the two disagree on purpose: when the platform build gate is off,
-    // fail_build/2 records BUILDS_TEMPORARILY_UNAVAILABLE on the build while
-    // template_status_after_failure(:builds_disabled) keeps the template "draft"
-    // so its name stays reusable. Reporting only "no completed build yet (state
-    // draft)" there would hide the one fact the caller needs.
-    const failed = builds?.find((build) => build.state === "failed");
-    if (failed) {
-        const why = buildError(failed);
-        return {
-            usable: false,
-            reason: why ? `last build failed: ${why}` : "last build failed",
-        };
-    }
-    if (state === "failed") {
-        return { usable: false, reason: "last build failed" };
-    }
-    if (builds && builds.length === 0) {
-        return { usable: false, reason: "no build has been started yet" };
+    if (state === "building" || state === "pending" || state === "queued") {
+        return { presence: "absent", why: `build is ${state}, no image published yet` };
     }
+    // Ready, but no image recorded. We genuinely cannot tell.
     return {
-        usable: false,
-        reason: `no completed build yet (state ${state ?? "unknown"})`,
+        presence: "unknown",
+        why: `template reports ${state ?? "no state"} but records no image - cannot confirm either way`,
     };
 }
-/**
- * The platform build gate being off is not the caller's fault and has a
- * different remedy from a broken Dockerfile: nothing to fix, retry later, and
- * the name is still reusable because the row stays a draft.
- */
-function buildsGatedOff(builds) {
-    return Boolean(builds?.some((build) => build.error_code === "BUILDS_TEMPORARILY_UNAVAILABLE"));
-}
-function buildError(build) {
-    if (!build)
-        return undefined;
-    const message = build.error_message ?? build.error;
-    if (message && build.error_code)
-        return `${build.error_code}: ${message}`;
-    return message ?? build.error_code ?? undefined;
-}
-function shortId(id) {
-    return id.length > 12 ? `${id.slice(0, 8)}...` : id;
+function fmtPresence(p) {
+    if (p === "present")
+        return chalk.green("present");
+    if (p === "absent")
+        return chalk.yellow("absent");
+    return chalk.dim("unverified");
 }
 function fmtBuildState(state) {
     if (!state)
         return chalk.dim("-");
-    if (state === "ready" || state === "success" || state === "complete")
+    if (state === "success" || state === "complete")
         return chalk.green(state);
-    if (state === "building" ||
-        state === "running" ||
-        state === "pending" ||
-        state === "queued" ||
-        state === "certifying" ||
-        state === "snapshotting")
+    if (state === "building" || state === "running" || state === "pending")
         return chalk.yellow(state);
-    if (state === "failed" || state === "error" || state === "cancelled")
+    if (state === "failed" || state === "error")
         return chalk.red(state);
     return chalk.dim(state);
 }
-function client() {
-    return new MiosaClient(loadConfig());
-}
-function readDockerfile(path) {
-    try {
-        const contents = readFileSync(path, "utf8");
-        if (contents.trim() === "") {
-            throw new UserError(`The Dockerfile at ${path} is empty.`, "A template needs at least a FROM line.");
-        }
-        return contents;
-    }
-    catch (err) {
-        if (err instanceof UserError)
-            throw err;
-        throw new UserError(`Cannot read Dockerfile at ${path}: ${err instanceof Error ? err.message : String(err)}`, "Pass --dockerfile with a path to a readable Dockerfile.");
-    }
-}
-/** Fetch the tenant's own templates, resolved to their full shape. */
-async function fetchTemplate(api, id) {
-    return unwrapTemplate(await api.apiGet(`/api/v1/sandbox-templates/${encodeURIComponent(id)}`));
-}
-async function fetchBuilds(api, id) {
-    return unwrapBuilds(await api.apiGet(`/api/v1/sandbox-templates/${encodeURIComponent(id)}/builds`));
-}
-/** Print the definitive existence/usability block for one custom template. */
-function printTemplateDetail(template, builds, opts) {
-    const status = usability(template, builds);
-    const reference = template.slug ?? template.id;
+// The whole point of a template is to reference it from your own code. Print
+// ready-to-paste create() calls for both SDKs and the CLI, using this exact
+// template's id, so a customer never has to guess the field name or hunt for
+// the id in a truncated table. If the template has no usable image yet, we say
+// so instead of implying the snippet will boot today.
+function printIntegrationSnippet(t) {
+    const ref = t.id;
+    const isReady = (templateState(t) ?? "") === "ready" && !!templateImage(t);
+    console.log(`  ${chalk.bold("Use this template")}`);
     console.log();
-    console.log(`  ${chalk.bold("ID")}        ${template.id}`);
-    console.log(`  ${chalk.bold("Name")}      ${template.name}`);
-    if (template.slug)
-        console.log(`  ${chalk.bold("Slug")}      ${template.slug}`);
-    console.log(`  ${chalk.bold("State")}     ${fmtTemplateState(templateState(template))}`);
-    console.log(`  ${chalk.bold("Exists")}    ${opts.verified
-        ? chalk.green("yes (confirmed by a follow-up read)")
-        : chalk.green("yes")}`);
-    console.log(`  ${chalk.bold("Usable")}    ${status.usable
-        ? chalk.green(`yes - ${status.reason}`)
-        : chalk.yellow(`no - ${status.reason}`)}`);
-    const image = templateImage(template);
-    console.log(`  ${chalk.bold("Image")}     ${image ?? chalk.dim("none yet")}`);
-    if (builds) {
-        console.log(`  ${chalk.bold("Builds")}    ${builds.length === 0
-            ? chalk.dim("none")
-            : `${builds.length} (latest ${shortId(builds[0]?.id ?? "")} ${builds[0]?.state ?? "unknown"})`}`);
-        const failure = buildError(builds.find((build) => build.state === "failed"));
-        if (failure)
-            console.log(`  ${chalk.bold("Failure")}   ${chalk.red(failure)}`);
-    }
-    const createdAt = templateCreatedAt(template);
-    if (createdAt)
-        console.log(`  ${chalk.bold("Created")}   ${createdAt}`);
-    if (template.updated_at)
-        console.log(`  ${chalk.bold("Updated")}   ${template.updated_at}`);
+    console.log(chalk.dim("  # Python SDK"));
+    console.log("  from miosa import Miosa");
+    console.log("  client = Miosa()");
+    console.log(`  sandbox = client.sandboxes.create(template_id=${JSON.stringify(ref)})`);
     console.log();
-    if (status.usable) {
-        console.log(chalk.dim(`  Boot it:   miosa sandbox create --template ${reference}`));
-    }
-    else {
-        console.log(chalk.yellow(`  Not bootable yet. "miosa sandbox create --template ${reference}" will fail until a build reaches "ready".`));
-        if (buildsGatedOff(builds)) {
-            // Nothing for the caller to fix, and re-running create with the same
-            // name works because the row stays a draft and create_template/3 upserts
-            // over a draft for the same tenant+slug.
-            console.log(chalk.dim("  This is a platform build gate, not a problem with your Dockerfile. Nothing to fix on your side."));
-            console.log(chalk.dim(`  The name stays yours: re-run the same create, or "miosa templates rebuild ${reference}", once builds are re-enabled.`));
-        }
-    }
-    console.log(chalk.dim(`  Builds:    miosa templates builds ${template.id}`));
-    console.log(chalk.dim(`  Re-verify: miosa templates get ${reference}`));
+    console.log(chalk.dim("  # TypeScript SDK"));
+    console.log('  import { Miosa } from "@miosa/sdk";');
+    console.log("  const client = new Miosa();");
+    console.log(`  const sandbox = await client.sandboxes.create({ templateId: ${JSON.stringify(ref)} });`);
     console.log();
+    console.log(chalk.dim("  # CLI"));
+    console.log(`  miosa sandbox create --template ${ref}`);
+    console.log();
+    if (!isReady) {
+        console.log(chalk.yellow("  Note: this template has no usable image yet, so create() will not boot it"));
+        console.log(chalk.dim(`  until its build completes. Check: miosa templates builds ${ref}`));
+        console.log();
+    }
 }
 export function register(program) {
     const templates = program
@@ -242,7 +128,9 @@ export function register(program) {
         .option("--json", "Output the complete catalog as JSON")
         .action(async (opts) => {
         try {
-            const raw = await client().apiGet("/api/v1/templates");
+            const config = loadConfig();
+            const client = new MiosaClient(config);
+            const raw = await client.apiGet("/api/v1/templates");
             const rows = productTemplates(raw);
             const filtered = opts.product
                 ? rows.filter((template) => template.product === opts.product)
@@ -268,7 +156,7 @@ export function register(program) {
             ]);
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
     templates
@@ -278,12 +166,13 @@ export function register(program) {
         .option("--json", "Output raw readiness rows")
         .action(async (id, opts) => {
         try {
-            const raw = await client().apiGet("/api/v1/templates");
+            const config = loadConfig();
+            const client = new MiosaClient(config);
+            const raw = await client.apiGet("/api/v1/templates");
             const rows = productTemplates(raw);
-            const template = rows.find((candidate) => candidate.id === id &&
-                (!opts.product || candidate.product === opts.product));
+            const template = rows.find((candidate) => candidate.id === id && (!opts.product || candidate.product === opts.product));
             if (!template)
-                throw new UserError(`Product template not found: ${id}`);
+                throw new Error(`Product template not found: ${id}`);
             const readiness = template.sizes ?? [];
             if (isJsonMode(opts)) {
                 printJson(readiness);
@@ -315,109 +204,99 @@ export function register(program) {
             ]);
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
     // list
     templates
         .command("list")
-        .description("List sandbox templates. Your own templates are listed first and marked yours.")
-        .option("--mine", "Show only templates this workspace created")
-        .option("--built-in", "Show only platform built-in templates")
-        .option("--verify", "Read each of your templates back individually to confirm it exists and fill in the slug and created date the catalog omits")
+        .description("List sandbox templates, distinguishing confirmed-absent from cannot-verify")
         .option("--json", "Output raw JSON")
         .action(async (opts) => {
+        const config = loadConfig();
+        const client = new MiosaClient(config);
+        const json = isJsonMode(opts);
+        const spinner = json ? null : spin("Fetching templates...");
+        const checkedAt = new Date().toISOString();
+        let rows;
         try {
-            const api = client();
-            const json = isJsonMode(opts);
-            const spinner = json ? null : spin("Fetching templates...");
-            let rows;
-            try {
-                rows = unwrapTemplates(await api.apiGet("/api/v1/sandbox-templates"));
-            }
-            catch (err) {
-                spinner?.fail("Could not fetch templates");
-                throw err;
-            }
-            let mine = rows.filter(isCustom);
-            const platform = rows.filter((row) => !isCustom(row));
-            if (opts.verify && mine.length > 0) {
-                spinner?.stop();
-                // The catalog rendering drops `slug` and `inserted_at` from custom
-                // rows, so the only way to report them is a per-row read. This also
-                // proves each row is individually retrievable, not just present in
-                // an aggregate list.
-                mine = await Promise.all(mine.map(async (row) => {
-                    try {
-                        return await fetchTemplate(api, row.id);
-                    }
-                    catch {
-                        return row;
-                    }
-                }));
-            }
+            rows = unwrapTemplates(await client.apiGet("/api/v1/sandbox-templates"));
+        }
+        catch (err) {
+            // The listing could NOT be verified. This is emphatically not "no
+            // templates" - reporting an empty list here would tell a customer their
+            // templates are gone when we simply failed to ask.
             spinner?.stop();
-            const selected = opts.mine
-                ? mine
-                : opts.builtIn
-                    ? platform
-                    : [...mine, ...platform];
+            const reason = err instanceof Error ? err.message : String(err);
+            if (json) {
+                printJson({
+                    listing: {
+                        state: "unverified",
+                        source: "live",
+                        checkedAt,
+                        reason,
+                    },
+                    templates: null,
+                });
+            }
+            else {
+                console.log();
+                console.log(`  ${chalk.yellow("Cannot verify")} - the template list could not be retrieved.`);
+                console.log(`  ${chalk.dim(reason)}`);
+                console.log(`  ${chalk.dim("This is NOT the same as having no templates. Run: miosa doctor")}`);
+            }
+            // Non-zero: a script must be able to tell an unverified listing from an
+            // empty one.
+            process.exitCode = 1;
+            return;
+        }
+        spinner?.stop();
+        try {
             if (json) {
-                printJson(selected);
+                printJson({
+                    // Never presented as current without saying when it was checked,
+                    // and never cached: this is a live read every time.
+                    listing: {
+                        state: "confirmed",
+                        source: "live",
+                        checkedAt,
+                        count: rows.length,
+                    },
+                    templates: rows.map((t) => {
+                        const { presence, why } = templatePresence(t);
+                        return { ...t, presence, presenceReason: why };
+                    }),
+                });
                 return;
             }
-            if (selected.length === 0) {
-                if (opts.mine) {
-                    console.log(chalk.dim("This workspace has not created any sandbox templates."));
-                    console.log(chalk.dim("  Create one: miosa templates create --name my-template --dockerfile ./Dockerfile"));
-                }
-                else {
-                    console.log(chalk.dim("No templates found."));
-                }
+            if (rows.length === 0) {
+                console.log(chalk.dim(`No templates. Confirmed empty by a live read at ${checkedAt}.`));
                 return;
             }
-            // The slug is what `sandbox create --template` accepts, and the
-            // catalog omits it for custom rows, so only offer the column when a
-            // value is actually known.
-            const anySlug = selected.some((row) => Boolean(row.slug));
-            renderTable(selected, [
-                {
-                    header: "SOURCE",
-                    key: (t) => isCustom(t) ? chalk.cyan("yours") : chalk.dim("built-in"),
-                    width: 10,
-                },
-                { header: "ID", key: (t) => t.id, width: 38 },
-                ...(anySlug
-                    ? [
-                        {
-                            header: "TEMPLATE REF",
-                            key: (t) => t.slug ?? (isCustom(t) ? chalk.dim("-") : t.id),
-                            width: 24,
-                        },
-                    ]
-                    : []),
-                { header: "NAME", key: "name", width: 26 },
+            renderTable(rows, [
+                { header: "ID", key: (t) => t.id.slice(0, 12), width: 14 },
+                { header: "NAME", key: "name", width: 28 },
                 {
                     header: "STATE",
                     key: (t) => fmtTemplateState(templateState(t)),
-                    width: 10,
+                    width: 12,
                 },
                 {
-                    header: "USABLE",
-                    key: (t) => usability(t).usable ? chalk.green("yes") : chalk.yellow("no"),
-                    width: 8,
+                    header: "IMAGE",
+                    key: (t) => fmtPresence(templatePresence(t).presence),
+                    width: 12,
                 },
                 {
-                    header: "IMAGE",
+                    header: "IMAGE ID",
                     key: (t) => {
                         const image = templateImage(t);
                         return image
-                            ? image.length > 28
-                                ? `${image.slice(0, 25)}...`
+                            ? image.length > 26
+                                ? `${image.slice(0, 23)}...`
                                 : image
                             : chalk.dim("-");
                     },
-                    width: 30,
+                    width: 28,
                 },
                 {
                     header: "CREATED",
@@ -428,280 +307,161 @@ export function register(program) {
                     width: 12,
                 },
             ]);
-            console.log();
-            if (mine.length === 0) {
-                console.log(chalk.yellow("  None of these are yours - this workspace has not created any templates."));
-                console.log(chalk.dim("  Create one: miosa templates create --name my-template --dockerfile ./Dockerfile"));
-            }
-            else {
-                console.log(opts.mine
-                    ? chalk.dim(`  ${mine.length} template${mine.length === 1 ? "" : "s"} created by this workspace. Platform built-ins are hidden; drop --mine to see them.`)
-                    : chalk.dim(`  ${mine.length} of these ${mine.length === 1 ? "is" : "are"} yours (SOURCE=yours); the other ${platform.length} are platform built-ins.`));
-                if (!opts.mine) {
-                    console.log(chalk.dim("  Only yours: miosa templates list --mine"));
-                }
-                const unusable = mine.filter((row) => !usability(row).usable);
-                if (unusable.length > 0) {
-                    // The catalog carries no build history, so the reason a row is
-                    // not usable takes a second request. Point at it rather than
-                    // leaving a bare "no" in the table.
-                    const first = unusable[0];
-                    console.log(chalk.yellow(`  ${unusable.length} of yours ${unusable.length === 1 ? "has" : "have"} no usable build yet, so ${unusable.length === 1 ? "it cannot" : "they cannot"} boot a sandbox.`));
-                    console.log(chalk.dim(`  Reason for each: miosa templates get ${first?.slug ?? first?.id ?? "<id>"}`));
-                }
-                if (!opts.verify) {
-                    console.log(chalk.dim("  The catalog omits the slug and created date of your own rows; add --verify to read them back individually."));
-                }
+            const unverified = rows.filter((t) => templatePresence(t).presence === "unknown");
+            if (unverified.length > 0) {
+                console.log();
+                console.log(chalk.dim(`  ${unverified.length} template(s) report no image and could not be confirmed either way.`));
             }
+            // The ID column is truncated to keep the table readable. Point users at
+            // the one command that prints the FULL, copyable id plus paste-ready
+            // SDK/CLI code for wiring the template into their own app.
             console.log();
+            console.log(chalk.dim(`  Run "miosa templates get <id>" for the full id and copy-paste integration code.`));
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
-    // get
+    // versions
     templates
-        .command("get <id>")
-        .description("Get sandbox template details, including whether it is usable")
+        .command("versions <id>")
+        .description("List a template's versions (a version is a build; specs are immutable)")
         .option("--json", "Output raw JSON")
         .action(async (id, opts) => {
         try {
-            const api = client();
+            const config = loadConfig();
+            const client = new MiosaClient(config);
             const json = isJsonMode(opts);
-            const spinner = json ? null : spin("Fetching template...");
-            let template;
-            try {
-                template = await fetchTemplate(api, id);
-            }
-            catch (err) {
-                spinner?.fail(`Template not found: ${id}`);
-                throw err;
-            }
-            // Builds are what decide usability, and the read is scoped to the same
-            // template, so fetch them rather than guessing from `status` alone.
-            // Built-ins have no build history endpoint of their own.
-            const builds = isCustom(template)
-                ? await fetchBuilds(api, template.id).catch(() => undefined)
-                : undefined;
+            const spinner = json ? null : spin("Fetching versions...");
+            const raw = (await client.apiGet(`/api/v1/sandbox-templates/${encodeURIComponent(id)}/versions`));
             spinner?.stop();
+            const rows = Array.isArray(raw) ? raw : (raw.data ?? []);
             if (json) {
-                printJson({
-                    ...template,
-                    usable: usability(template, builds).usable,
-                    usable_reason: usability(template, builds).reason,
-                    ...(builds ? { builds } : {}),
-                });
+                printJson(rows);
                 return;
             }
-            printTemplateDetail(template, builds, { verified: false });
-        }
-        catch (err) {
-            handleError(err, opts);
-        }
-    });
-    // create
-    templates
-        .command("create")
-        .description("Create a sandbox template from a Dockerfile")
-        .requiredOption("--name <name>", "Template name")
-        .requiredOption("--dockerfile <path>", "Path to Dockerfile to build the template from")
-        .option("--description <text>", "Human description of the template")
-        .option("--no-verify", "Skip the follow-up read that confirms the template exists")
-        .option("--json", "Output raw JSON")
-        .action(async (opts) => {
-        const json = isJsonMode(opts);
-        try {
-            const dockerfile = readDockerfile(opts.dockerfile);
-            const api = client();
-            const spinner = json
-                ? null
-                : spin(`Creating template ${opts.name}...`);
-            let template;
-            try {
-                template = unwrapTemplate(await api.apiPost("/api/v1/sandbox-templates", {
-                    name: opts.name,
-                    dockerfile,
-                    ...(opts.description ? { description: opts.description } : {}),
-                }));
-            }
-            catch (err) {
-                // Leaving the spinner spinning under an error message was how the
-                // customer's failed create looked like a hung command.
-                spinner?.fail(`Could not create template ${opts.name}`);
-                throw err;
-            }
-            spinner?.succeed(`Created template ${template.name}`);
-            // The create response is rendered from the in-memory row, so its
-            // `current_build_id` is still null even though the controller has
-            // already enqueued the initial build. Read the row and its builds
-            // back to give a definitive answer instead of an optimistic one.
-            let verified = false;
-            let builds;
-            if (opts.verify) {
-                try {
-                    template = await fetchTemplate(api, template.id);
-                    verified = true;
-                }
-                catch {
-                    verified = false;
-                }
-                builds = await fetchBuilds(api, template.id).catch(() => undefined);
-            }
-            if (json) {
-                printJson({
-                    ...template,
-                    verified,
-                    usable: usability(template, builds).usable,
-                    usable_reason: usability(template, builds).reason,
-                    ...(builds ? { builds } : {}),
-                });
+            if (rows.length === 0) {
+                console.log(chalk.dim("No versions yet."));
                 return;
             }
-            printTemplateDetail(template, builds, { verified });
-            if (opts.verify && !verified) {
-                console.log(chalk.yellow("  Warning: the create call returned 201 but the follow-up read did not find this template."));
-                console.log(chalk.dim(`  Check again: miosa templates get ${template.id}   (or: miosa templates list --mine)`));
-                console.log();
-            }
+            renderTable(rows, [
+                {
+                    header: "VERSION",
+                    key: (v) => (v.current ? chalk.bold(`v${v.version} *`) : `v${v.version}`),
+                    width: 10,
+                },
+                { header: "REF", key: (v) => v.ref ?? chalk.dim("-"), width: 26 },
+                {
+                    header: "STATE",
+                    key: (v) => fmtBuildState(v.state),
+                    width: 12,
+                },
+                {
+                    // Whether this version can actually be run or migrated to. A failed
+                    // build is listed - you need to see it to understand why the next
+                    // version is unavailable - but it is not usable.
+                    header: "USABLE",
+                    key: (v) => (v.usable ? chalk.green("yes") : chalk.dim("no")),
+                    width: 8,
+                },
+                {
+                    header: "IMAGE",
+                    key: (v) => v.image_id ?? chalk.dim("-"),
+                    width: 26,
+                },
+                {
+                    header: "CREATED",
+                    key: (v) => (v.created_at ? String(v.created_at).slice(0, 10) : chalk.dim("-")),
+                    width: 12,
+                },
+            ]);
+            console.log();
+            console.log(chalk.dim("  * = current. Specs are immutable: editing a template mints a new version,"));
+            console.log(chalk.dim("  and existing sandboxes keep running the version they were created from."));
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
-    // update
+    // get
     templates
-        .command("update <id>")
-        .description("Update a template's Dockerfile. Replaces the spec in place while it has no usable build; otherwise starts a new build from the new Dockerfile.")
-        .requiredOption("--dockerfile <path>", "Path to the new Dockerfile")
-        .option("--description <text>", "Replace the description")
+        .command("get <id>")
+        .description("Get sandbox template details")
         .option("--json", "Output raw JSON")
         .action(async (id, opts) => {
-        const json = isJsonMode(opts);
         try {
-            const dockerfile = readDockerfile(opts.dockerfile);
-            const api = client();
-            const spinner = json ? null : spin(`Reading template ${id}...`);
-            let existing;
-            try {
-                existing = await fetchTemplate(api, id);
-            }
-            catch (err) {
-                spinner?.fail(`Template not found: ${id}`);
-                throw err;
-            }
-            if (!isCustom(existing)) {
-                spinner?.fail(`${existing.name} is a platform built-in`);
-                throw new UserError(`${existing.id} is a platform built-in template and cannot be updated.`, "Create your own template instead: miosa templates create --name <name> --dockerfile ./Dockerfile");
-            }
-            const state = templateState(existing);
-            // The API has two update mechanisms and which one applies depends on
-            // whether the row already owns a usable image:
-            //
-            //   draft / failed -> POST /api/v1/sandbox-templates upserts the row
-            //     in place for the same tenant+slug, replacing build_spec and
-            //     clearing image_id/current_build_id.
-            //   ready / building / archived -> that upsert is a real uniqueness
-            //     collision, so the supported path is a new build from the new
-            //     spec: POST /api/v1/sandbox-templates/:id/builds.
-            const replaceInPlace = state === "draft" || state === "failed";
-            let template;
-            let build;
-            if (replaceInPlace) {
-                spinner?.start(`Replacing the spec of ${existing.name}...`);
-                try {
-                    template = unwrapTemplate(await api.apiPost("/api/v1/sandbox-templates", {
-                        name: existing.name,
-                        ...(existing.slug ? { slug: existing.slug } : {}),
-                        dockerfile,
-                        ...(opts.description !== undefined
-                            ? { description: opts.description }
-                            : existing.description
-                                ? { description: existing.description }
-                                : {}),
-                    }));
-                }
-                catch (err) {
-                    spinner?.fail(`Could not update ${existing.name}`);
-                    throw err;
-                }
-                spinner?.succeed(`Replaced the spec of ${template.name} in place (it had no usable build)`);
-            }
-            else {
-                spinner?.start(`Starting a new build of ${existing.name}...`);
-                try {
-                    const raw = await api.apiPost(`/api/v1/sandbox-templates/${encodeURIComponent(existing.id)}/builds`, { dockerfile });
-                    build = raw.data ?? raw;
-                }
-                catch (err) {
-                    spinner?.fail(`Could not start a new build of ${existing.name}`);
-                    throw err;
-                }
-                spinner?.succeed(`Started build ${shortId(build.id)} of ${existing.name} from the new Dockerfile`);
-                template = await fetchTemplate(api, existing.id).catch(() => existing);
-            }
-            const builds = await fetchBuilds(api, template.id).catch(() => undefined);
+            const config = loadConfig();
+            const client = new MiosaClient(config);
+            const json = isJsonMode(opts);
+            const spinner = json ? null : spin("Fetching template...");
+            const tmpl = unwrapTemplate(await client.apiGet(`/api/v1/sandbox-templates/${encodeURIComponent(id)}`));
+            spinner?.stop();
             if (json) {
-                printJson({
-                    ...template,
-                    mechanism: replaceInPlace ? "spec_replaced" : "new_build",
-                    ...(build ? { build } : {}),
-                    usable: usability(template, builds).usable,
-                    usable_reason: usability(template, builds).reason,
-                    ...(builds ? { builds } : {}),
-                });
+                printJson(tmpl);
                 return;
             }
-            // Which of the two mechanisms ran is the one thing a caller must not
-            // have to guess, so state it on stdout rather than only in the
-            // spinner line (which ora writes to stderr and which is lost the
-            // moment output is redirected).
             console.log();
-            console.log(replaceInPlace
-                ? chalk.dim(`  ${existing.name} had no usable build, so its stored Dockerfile was replaced in place\n  and a fresh build was queued. Same template ID, same name.`)
-                : chalk.dim(`  ${existing.name} already had a usable image, so its stored spec was not overwritten;\n  the new Dockerfile is building as a new build instead.`));
-            printTemplateDetail(template, builds, { verified: true });
+            console.log(`  ${chalk.bold("ID")}       ${tmpl.id}`);
+            console.log(`  ${chalk.bold("Name")}     ${tmpl.name}`);
+            if (tmpl.slug)
+                console.log(`  ${chalk.bold("Slug")}     ${tmpl.slug}`);
+            console.log(`  ${chalk.bold("State")}    ${fmtTemplateState(templateState(tmpl))}`);
+            const image = templateImage(tmpl);
+            if (image)
+                console.log(`  ${chalk.bold("Image")}    ${image}`);
+            const createdAt = templateCreatedAt(tmpl);
+            if (createdAt)
+                console.log(`  ${chalk.bold("Created")}  ${createdAt}`);
+            if (tmpl.updated_at)
+                console.log(`  ${chalk.bold("Updated")}  ${tmpl.updated_at}`);
+            console.log();
+            printIntegrationSnippet(tmpl);
+            console.log(chalk.dim(`  Run "miosa templates builds ${tmpl.id}" to view build history.`));
+            console.log();
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
-    // rebuild
+    // create
     templates
-        .command("rebuild <id>")
-        .description("Start a new build of an existing template, optionally from a new Dockerfile")
-        .option("--dockerfile <path>", "Build from this Dockerfile instead of the template's stored spec")
+        .command("create")
+        .description("Create a sandbox template from a Dockerfile")
+        .requiredOption("--name <name>", "Template name")
+        .requiredOption("--dockerfile <path>", "Path to Dockerfile to build the template from")
         .option("--json", "Output raw JSON")
-        .action(async (id, opts) => {
-        const json = isJsonMode(opts);
+        .action(async (opts) => {
         try {
-            const api = client();
-            const body = opts.dockerfile
-                ? { dockerfile: readDockerfile(opts.dockerfile) }
-                : {};
-            const spinner = json ? null : spin(`Starting a build of ${id}...`);
-            let build;
+            let dockerfileContent;
             try {
-                const raw = await api.apiPost(`/api/v1/sandbox-templates/${encodeURIComponent(id)}/builds`, body);
-                build = raw.data ?? raw;
+                dockerfileContent = readFileSync(opts.dockerfile, "utf8");
             }
             catch (err) {
-                spinner?.fail(`Could not start a build of ${id}`);
-                throw err;
-            }
-            spinner?.succeed(`Started build ${shortId(build.id)}`);
-            if (json) {
-                printJson(build);
+                console.error(chalk.red(`Cannot read Dockerfile at ${opts.dockerfile}: ${err instanceof Error ? err.message : String(err)}`));
+                process.exit(1);
+            }
+            const config = loadConfig();
+            const client = new MiosaClient(config);
+            const spinner = spin(`Creating template ${opts.name}...`);
+            const tmpl = unwrapTemplate(await client.apiPost("/api/v1/sandbox-templates", {
+                name: opts.name,
+                dockerfile: dockerfileContent,
+            }));
+            spinner.succeed(`Created template ${tmpl.name}`);
+            if (opts.json) {
+                console.log(JSON.stringify(tmpl, null, 2));
                 return;
             }
             console.log();
-            console.log(`  ${chalk.bold("Build")}  ${build.id}`);
-            console.log(`  ${chalk.bold("State")}  ${fmtBuildState(build.state)}`);
+            console.log(`  ${chalk.bold("ID")}     ${tmpl.id}`);
+            console.log(`  ${chalk.bold("Name")}   ${tmpl.name}`);
+            console.log(`  ${chalk.bold("State")}  ${fmtTemplateState(tmpl.state)}`);
             console.log();
-            console.log(chalk.dim(`  Track it: miosa templates builds ${id}`));
+            console.log(chalk.dim(`  Run "miosa templates builds ${tmpl.id}" to track the build.`));
             console.log();
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
     // builds
@@ -711,17 +471,11 @@ export function register(program) {
         .option("--json", "Output raw JSON")
         .action(async (id, opts) => {
         try {
-            const api = client();
+            const config = loadConfig();
+            const client = new MiosaClient(config);
             const json = isJsonMode(opts);
             const spinner = json ? null : spin("Fetching builds...");
-            let rows;
-            try {
-                rows = await fetchBuilds(api, id);
-            }
-            catch (err) {
-                spinner?.fail(`Could not fetch builds for ${id}`);
-                throw err;
-            }
+            const rows = unwrapBuilds(await client.apiGet(`/api/v1/sandbox-templates/${encodeURIComponent(id)}/builds`));
             spinner?.stop();
             if (json) {
                 printJson(rows);
@@ -729,20 +483,14 @@ export function register(program) {
             }
             if (rows.length === 0) {
                 console.log(chalk.dim("No builds found."));
-                console.log(chalk.dim(`  Start one: miosa templates rebuild ${id}`));
                 return;
             }
             renderTable(rows, [
-                { header: "BUILD ID", key: (b) => b.id, width: 38 },
+                { header: "BUILD ID", key: (b) => b.id.slice(0, 12), width: 14 },
                 {
                     header: "STATE",
                     key: (b) => fmtBuildState(b.state),
-                    width: 14,
-                },
-                {
-                    header: "IMAGE",
-                    key: (b) => b.image_id ?? b.image_digest ?? chalk.dim("-"),
-                    width: 30,
+                    width: 12,
                 },
                 {
                     header: "STARTED",
@@ -760,22 +508,17 @@ export function register(program) {
                 },
                 {
                     header: "ERROR",
-                    key: (b) => {
-                        // The API reports failures as error_code/error_message; reading
-                        // only `error` meant every failed build showed a blank column.
-                        const message = buildError(b);
-                        return message
-                            ? chalk.red(message.length > 40
-                                ? `${message.slice(0, 37)}...`
-                                : message)
-                            : chalk.dim("-");
-                    },
-                    width: 42,
+                    key: (b) => b.error
+                        ? chalk.red(b.error.length > 30
+                            ? `${b.error.slice(0, 27)}...`
+                            : b.error)
+                        : chalk.dim("-"),
+                    width: 32,
                 },
             ]);
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
     // delete
@@ -801,28 +544,16 @@ export function register(program) {
                     process.exit(0);
                 }
             }
-            const api = client();
-            const json = isJsonMode(opts);
-            const spinner = json ? null : spin("Deleting template...");
-            let result;
-            try {
-                result = await api.apiDelete(`/api/v1/sandbox-templates/${encodeURIComponent(id)}`);
-            }
-            catch (err) {
-                spinner?.fail(`Could not delete template ${id}`);
-                // TEMPLATE_IN_USE is a refusal with a specific remedy, not a bug.
-                if (err instanceof ApiResponseError &&
-                    err.code === "TEMPLATE_IN_USE") {
-                    throw new UserError(err.message, "Stop the sandboxes booted from this template, or wait for its build to finish, then retry.");
-                }
-                throw err;
-            }
-            spinner?.succeed("Template deleted");
-            if (json)
-                printJson(result ?? { ok: true });
+            const config = loadConfig();
+            const client = new MiosaClient(config);
+            const spinner = spin("Deleting template...");
+            const result = await client.apiDelete(`/api/v1/sandbox-templates/${encodeURIComponent(id)}`);
+            spinner.succeed("Template deleted");
+            if (opts.json)
+                console.log(JSON.stringify(result ?? { ok: true }, null, 2));
         }
         catch (err) {
-            handleError(err, opts);
+            handleError(err);
         }
     });
 }