@moldesk/cli 0.0.5 → 0.0.6

package/dist/commands/cloud.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+import { type CloudAccountDeps, type CloudRunDeps } from "@moldesk/core";
+/** Exit code for a cloud error code that is more specific than "run failed" (7), or undefined. */
+export declare function cloudExitCodeForCode(code: string | undefined): number | undefined;
+export declare function cloudExitCode(error: unknown): number;
+export interface CloudCommandHooks {
+    /** Resolves provider/backend wiring for recover and cache commands; injected for tests. */
+    runDeps?: () => Promise<CloudRunDeps>;
+    confirm?: (question: string) => Promise<boolean>;
+}
+export declare function registerCloudCommand(program: Command, deps?: CloudAccountDeps, hooks?: CloudCommandHooks): void;

package/dist/commands/cloud.js

@@ -0,0 +1,282 @@
+import { MoldeskError, connectCloudProvider, createRunpodCloudDeps, disconnectCloudProvider, executeCloudCacheDeletion, getCloudStatus, listCloudCaches, listCloudResources, planCloudCacheDeletion, recoverCloudRun, } from "@moldesk/core";
+import { confirm } from "../utils/confirm.js";
+import { readSecret } from "../utils/secret-input.js";
+/** Cloud exit codes live beside the run codes (0/7/8 outcomes, 2-5 usage). */
+const CLOUD_EXIT_CODES = {
+    CREDENTIAL_UNSUPPORTED_PROVIDER: 2,
+    CREDENTIAL_INVALID: 2,
+    CREDENTIAL_MISSING: 11,
+    CLOUD_AUTH_FAILED: 11,
+    CLOUD_FORBIDDEN: 11,
+    CREDENTIAL_STORE_UNAVAILABLE: 11,
+    CLOUD_PAYMENT_REQUIRED: 12,
+    CLOUD_RATE_LIMITED: 12,
+    CLOUD_CAPACITY_UNAVAILABLE: 12,
+    CLOUD_UNAVAILABLE: 12,
+    CLOUD_BUDGET_REQUIRED: 2,
+    CLOUD_LIFETIME_REQUIRED: 2,
+    CLOUD_BUDGET_EXCEEDED: 2,
+    CLOUD_GPU_UNKNOWN: 2,
+    CLOUD_GPU_INELIGIBLE: 2,
+    CLOUD_OPTIONS_REQUIRED: 2,
+    CLOUD_OPTIONS_WITHOUT_CLOUD: 2,
+    CLOUD_RUNTIME_UNSUPPORTED: 2,
+    CLOUD_COMPANION_INPUTS_UNSUPPORTED: 2,
+    CLOUD_MODEL_UNSUPPORTED: 4,
+    // Consent and safety refusals: nothing was provisioned.
+    CLOUD_APPROVAL_MISMATCH: 14,
+    CLOUD_APPROVAL_EXPIRED: 14,
+    CLOUD_REQUOTE_REQUIRED: 14,
+    CLOUD_ACKNOWLEDGMENT_REQUIRED: 14,
+    CLOUD_WORKER_BUNDLE_UNCONFIGURED: 14,
+    CLOUD_WORKER_BUNDLE_INVALID: 14,
+    CLOUD_UNRESOLVED_RESOURCES: 13,
+    CLOUD_RUN_UNKNOWN: 2,
+    CLOUD_CACHE_IN_USE: 2,
+};
+/** Exit code for a cloud error code that is more specific than "run failed" (7), or undefined. */
+export function cloudExitCodeForCode(code) {
+    return code !== undefined && code in CLOUD_EXIT_CODES && CLOUD_EXIT_CODES[code] >= 11 ? CLOUD_EXIT_CODES[code] : undefined;
+}
+export function cloudExitCode(error) {
+    return error instanceof MoldeskError && error.code in CLOUD_EXIT_CODES ? CLOUD_EXIT_CODES[error.code] : 10;
+}
+function report(error, json) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof MoldeskError ? error.code : undefined;
+    const remediation = error instanceof MoldeskError ? error.remediation : undefined;
+    if (json)
+        console.log(JSON.stringify({ status: "error", code, message, remediation }, null, 2));
+    else {
+        console.error(message);
+        if (remediation)
+            console.error(remediation);
+    }
+    process.exitCode = cloudExitCode(error);
+}
+async function readKeyFromStdin() {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin)
+        data += chunk;
+    return data.replace(/\r?\n[\s\S]*$/, "");
+}
+export function registerCloudCommand(program, deps = {}, hooks = {}) {
+    const resolveRunDeps = hooks.runDeps ?? (() => createRunpodCloudDeps({ paths: deps.paths, store: deps.store }));
+    const ask = hooks.confirm ?? ((question) => confirm(question));
+    const cloud = program.command("cloud").description("Connect and inspect cloud compute accounts");
+    cloud
+        .command("connect <provider>")
+        .description("Store a provider API key in the OS credential store after validating it")
+        .option("--key-stdin", "read the key from standard input instead of prompting (never pass keys as arguments)")
+        .option("--json", "print the result as JSON")
+        .action(async (provider, options) => {
+        try {
+            if (!options.keyStdin && process.stdin.isTTY !== true) {
+                throw new MoldeskError({
+                    code: "CREDENTIAL_INVALID",
+                    message: "No terminal is attached to prompt for the key.",
+                    remediation: "Run in a terminal, or pipe the key with --key-stdin.",
+                });
+            }
+            const key = options.keyStdin
+                ? await readKeyFromStdin()
+                : await readSecret({ input: process.stdin, output: process.stderr, prompt: `${provider} API key (input hidden): ` });
+            const result = await connectCloudProvider(provider, key.trim(), deps);
+            if (options.json)
+                console.log(JSON.stringify({ status: "connected", ...result }, null, 2));
+            else {
+                console.log(`Connected to ${provider}. Key stored in the OS credential store.`);
+                if (result.overriddenBy) {
+                    console.log(`Note: a key from the environment still takes precedence over the stored key.`);
+                }
+            }
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+    cloud
+        .command("disconnect <provider>")
+        .description("Remove the stored API key (an environment variable is left alone)")
+        .option("--json", "print the result as JSON")
+        .action(async (provider, options) => {
+        try {
+            const result = await disconnectCloudProvider(provider, deps);
+            if (options.json)
+                console.log(JSON.stringify({ status: "ok", ...result }, null, 2));
+            else
+                console.log(result.removed ? `Removed the stored ${provider} key.` : `No stored ${provider} key to remove.`);
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+    cloud
+        .command("status")
+        .description("Show credential source, live connection and unfinished cloud work")
+        .option("--provider <name>", "cloud provider", "runpod")
+        .option("--json", "print the result as JSON")
+        .action(async (options) => {
+        try {
+            const status = await getCloudStatus(options.provider, deps);
+            if (options.json) {
+                console.log(JSON.stringify(status, null, 2));
+            }
+            else {
+                console.log(`Provider:    ${status.provider}`);
+                console.log(`Credential:  ${status.credential.source === "none" ? "none (run `moldesk cloud connect " + status.provider + "`)" : status.credential.source}`);
+                if (status.connection) {
+                    console.log(`Connection:  ${status.connection.ok ? "ok" : `failed (${status.connection.code}): ${status.connection.message}`}`);
+                }
+                console.log(`Open jobs:   ${status.journal.openJobs.length}`);
+                console.log(`Unresolved resources: ${status.journal.unresolvedResources.length}`);
+                for (const job of status.journal.openJobs)
+                    console.log(`  job ${job.runId}: ${job.stage} (${job.status}), deadline ${job.deadlineAt}`);
+            }
+            if (status.connection && !status.connection.ok)
+                process.exitCode = cloudExitCode(new MoldeskError({ code: status.connection.code, message: status.connection.message }));
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+    cloud
+        .command("resources")
+        .description("List cloud resources this installation owns, orphans and owed cleanup")
+        .option("--provider <name>", "cloud provider", "runpod")
+        .option("--json", "print the result as JSON")
+        .action(async (options) => {
+        try {
+            const listing = await listCloudResources(options.provider, deps);
+            if (options.json) {
+                console.log(JSON.stringify(listing, null, 2));
+                return;
+            }
+            console.log(`Owned by this installation (${listing.owned.length}):`);
+            for (const entry of listing.owned) {
+                const detail = entry.kind === "pod"
+                    ? `${entry.status}${entry.costUsdPerHour != null ? `, $${entry.costUsdPerHour}/h` : ""}`
+                    : `${entry.sizeGb} GB volume (retained storage is billed)`;
+                console.log(`  ${entry.kind} ${entry.record.providerId}  ${entry.record.name}  ${detail}`);
+            }
+            if (listing.orphaned.length > 0) {
+                console.log(`Orphaned (named like ours, no journal owner; not deleted automatically) (${listing.orphaned.length}):`);
+                for (const entry of listing.orphaned)
+                    console.log(`  ${entry.providerId}  ${entry.name}`);
+            }
+            if (listing.cleanupOwed.length > 0) {
+                console.log(`Cleanup owed (${listing.cleanupOwed.length}):`);
+                for (const record of listing.cleanupOwed)
+                    console.log(`  ${record.providerId}  ${record.name}  ${record.state}`);
+            }
+            console.log(`Other resources on the account (not managed by MoleculeDesk): ${listing.unmanagedCount}`);
+            const changed = listing.reconciliation;
+            if (changed.adopted.length + changed.abandoned.length + changed.vanished.length > 0) {
+                console.log(`Journal reconciled: ${changed.adopted.length} adopted, ${changed.abandoned.length} never created, ${changed.vanished.length} already gone.`);
+            }
+            if (listing.orphaned.length > 0 || listing.cleanupOwed.length > 0)
+                process.exitCode = 13;
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+    cloud
+        .command("recover <run-id>")
+        .description("Resume transfer and cleanup for an interrupted or failed cloud run (never restarts inference)")
+        .option("--terminate", "also terminate a machine whose job is still running (loses unfinished results)")
+        .option("--json", "print the result as JSON")
+        .action(async (runId, options) => {
+        try {
+            const runDeps = await resolveRunDeps();
+            const result = await recoverCloudRun(runId, runDeps, { terminateRunning: options.terminate });
+            if (options.json)
+                console.log(JSON.stringify(result, null, 2));
+            else {
+                console.log(`Run ${result.runId}: ${result.status}${result.collected ? " (results downloaded and verified)" : ""}.`);
+                if (result.cleanup.confirmed)
+                    console.log("Cloud resources: confirmed deleted.");
+                else if (result.status === "running")
+                    console.log("The job is still running; its machine was left alone. Re-run with --terminate to stop it.");
+                else
+                    console.error(`Cleanup still pending: ${result.cleanup.pending.map((resource) => `${resource.role} ${resource.providerId}`).join(", ")}.`);
+            }
+            if (!result.cleanup.confirmed)
+                process.exitCode = 13;
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+    const cache = cloud.command("cache").description("Inspect and delete retained model caches (billed network volumes)");
+    cache
+        .command("list")
+        .description("List retained caches and whether their volumes still exist")
+        .option("--json", "print the result as JSON")
+        .action(async (options) => {
+        try {
+            const listing = await listCloudCaches(await resolveRunDeps());
+            if (options.json)
+                return void console.log(JSON.stringify(listing, null, 2));
+            if (listing.length === 0)
+                return void console.log("No retained caches.");
+            for (const entry of listing) {
+                const volume = entry.volumeExists === undefined ? "volume status unknown" : entry.volumeExists ? `volume ${entry.cache.volumeId}${entry.volumeSizeGb ? ` (${entry.volumeSizeGb} GB, billed)` : ""}` : "volume no longer exists";
+                console.log(`${entry.cache.model} ${entry.cache.modelVersion}  ${entry.cache.state}  ${entry.cache.datacenterId}  ${volume}`);
+            }
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+    cache
+        .command("delete <model>")
+        .description("Delete the retained volume(s) holding a model's cache (billing stops)")
+        .option("--yes", "skip the confirmation prompt")
+        .option("--json", "print the result as JSON")
+        .action(async (model, options) => {
+        try {
+            const runDeps = await resolveRunDeps();
+            const plan = await planCloudCacheDeletion(model, runDeps);
+            if (plan.volumes.length === 0) {
+                if (options.json)
+                    console.log(JSON.stringify({ status: "nothing-to-delete", model }, null, 2));
+                else
+                    console.log(`No retained cache for ${model}.`);
+                return;
+            }
+            if (!options.json) {
+                console.error(`This permanently deletes ${plan.volumes.length} volume(s) and everything on them:`);
+                for (const volume of plan.volumes)
+                    console.error(`  ${volume.volumeId}  ${volume.datacenterId}${volume.sizeGb ? `  ${volume.sizeGb} GB` : ""}`);
+                for (const blocker of plan.blockers)
+                    console.error(`  Blocked: ${blocker}`);
+            }
+            if (plan.blockers.length === 0 && !options.yes) {
+                if (!(await ask("Delete these volumes?"))) {
+                    if (options.json)
+                        console.log(JSON.stringify({ status: "declined", plan }, null, 2));
+                    else
+                        console.error("Not deleted.");
+                    process.exitCode = 2;
+                    return;
+                }
+            }
+            const result = await executeCloudCacheDeletion(plan, runDeps);
+            if (options.json)
+                console.log(JSON.stringify({ status: result.failed.length > 0 ? "partial" : "deleted", ...result }, null, 2));
+            else {
+                for (const item of result.deleted)
+                    console.log(`Deleted volume ${item.volumeId}.`);
+                for (const item of result.failed)
+                    console.error(`Could not delete ${item.volumeId}: ${item.reason}`);
+            }
+            if (result.failed.length > 0)
+                process.exitCode = 12;
+        }
+        catch (error) {
+            report(error, options.json);
+        }
+    });
+}

package/dist/commands/cloud.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/cloud.test.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+import { CloudJournal, CredentialStore, MoldeskError, getMoldeskPaths } from "@moldesk/core";
+import { cloudExitCode, registerCloudCommand } from "./cloud.js";
+const KEY = "rpa_TESTKEY0123456789";
+let home;
+let out;
+let err;
+let stored;
+beforeEach(() => {
+    home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk cli cloud "));
+    stored = new Map();
+    out = [];
+    err = [];
+    vi.spyOn(console, "log").mockImplementation((...a) => void out.push(a.join(" ")));
+    vi.spyOn(console, "error").mockImplementation((...a) => void err.push(a.join(" ")));
+    process.exitCode = undefined;
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    process.exitCode = undefined;
+    fs.rmSync(home, { recursive: true, force: true });
+});
+function backend() {
+    return {
+        async get(service, account) {
+            return stored.get(`${service}/${account}`) ?? null;
+        },
+        async set(service, account, secret) {
+            stored.set(`${service}/${account}`, secret);
+        },
+        async delete(service, account) {
+            return stored.delete(`${service}/${account}`);
+        },
+    };
+}
+function provider(validate, pods = []) {
+    return {
+        name: "fake",
+        validateCredentials: validate,
+        getCatalog: async () => {
+            throw new Error("unused");
+        },
+        createPod: async () => {
+            throw new Error("must not create");
+        },
+        getPod: async () => null,
+        listPods: async () => pods,
+        terminatePod: async () => {
+            throw new Error("must not terminate");
+        },
+        createVolume: async () => {
+            throw new Error("must not create");
+        },
+        getVolume: async () => null,
+        listVolumes: async () => [],
+        deleteVolume: async () => {
+            throw new Error("must not delete");
+        },
+    };
+}
+async function run(options, ...args) {
+    const program = new Command();
+    program.exitOverride();
+    registerCloudCommand(program, {
+        paths: getMoldeskPaths({ MOLDESK_HOME: home }),
+        store: new CredentialStore({ backend: backend(), env: options.env ?? {} }),
+        createProvider: () => provider(options.validate ?? (async () => ({ ok: true, checkedAt: "t" })), options.pods),
+    });
+    await program.parseAsync(["cloud", ...args], { from: "user" });
+}
+describe("cloud commands", () => {
+    it("connect refuses to prompt without a terminal and without --key-stdin", async () => {
+        const original = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+        Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+        try {
+            await run({}, "connect", "runpod");
+        }
+        finally {
+            if (original)
+                Object.defineProperty(process.stdin, "isTTY", original);
+            else
+                delete process.stdin.isTTY;
+        }
+        expect(err.join("\n")).toContain("No terminal is attached");
+        expect(process.exitCode).toBe(2);
+        expect(stored.size).toBe(0);
+    });
+    it("status without a credential is explicit and exits cleanly", async () => {
+        await run({}, "status");
+        expect(out.join("\n")).toContain("Credential:  none");
+        expect(process.exitCode).toBeUndefined();
+    });
+    it("status with a working key reports ok and never prints the key", async () => {
+        await run({ env: { RUNPOD_API_KEY: KEY } }, "status", "--json");
+        const printed = out.join("\n");
+        expect(printed).not.toContain(KEY);
+        expect(JSON.parse(printed)).toMatchObject({ credential: { source: "env" }, connection: { ok: true } });
+    });
+    it("status exits 11 when the provider rejects the key", async () => {
+        await run({
+            env: { RUNPOD_API_KEY: KEY },
+            validate: async () => {
+                throw new MoldeskError({ code: "CLOUD_AUTH_FAILED", message: "Runpod rejected the API key.", remediation: "x" });
+            },
+        }, "status");
+        expect(out.join("\n")).toContain("failed (CLOUD_AUTH_FAILED)");
+        expect(process.exitCode).toBe(11);
+    });
+    it("disconnect reports whether anything was removed", async () => {
+        stored.set("moldesk/runpod:default", KEY);
+        await run({}, "disconnect", "runpod");
+        expect(out.join("\n")).toContain("Removed the stored runpod key.");
+        out.length = 0;
+        await run({}, "disconnect", "runpod");
+        expect(out.join("\n")).toContain("No stored runpod key to remove.");
+    });
+    it("resources needs a credential and reports exit 11 otherwise", async () => {
+        await run({}, "resources", "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ status: "error", code: "CREDENTIAL_MISSING" });
+        expect(process.exitCode).toBe(11);
+    });
+    it("resources lists orphans and exits 13 so scripts notice owed cleanup", async () => {
+        const journal = CloudJournal.open(getMoldeskPaths({ MOLDESK_HOME: home }));
+        const prefix = journal.clientId.replace(/-/g, "").slice(0, 8);
+        journal.close();
+        await run({
+            env: { RUNPOD_API_KEY: KEY },
+            pods: [{ id: "podX", name: `moldesk-${prefix}-deadbeef-gpu`, status: "RUNNING", dataCenterId: null, costUsdPerHour: 0.5, createdAt: null }],
+        }, "resources");
+        const printed = out.join("\n");
+        expect(printed).toContain("Orphaned");
+        expect(printed).toContain("podX");
+        expect(printed).toContain("Other resources on the account (not managed by MoleculeDesk): 0");
+        expect(process.exitCode).toBe(13);
+    });
+});
+describe("recover and cache commands", () => {
+    const volumes = new Map();
+    const deleted = [];
+    function runDeps() {
+        const provider = {
+            name: "runpod",
+            listVolumes: async () => [...volumes.values()],
+            getVolume: async (id) => volumes.get(id) ?? null,
+            deleteVolume: async (id) => {
+                volumes.delete(id);
+                deleted.push(id);
+                return { id, alreadyAbsent: false };
+            },
+        };
+        return { provider, paths: getMoldeskPaths({ MOLDESK_HOME: home }), accountScope: "acct" };
+    }
+    async function exec(confirmAnswer, ...args) {
+        const program = new Command();
+        program.exitOverride();
+        registerCloudCommand(program, {}, { runDeps: async () => runDeps(), confirm: async () => confirmAnswer });
+        await program.parseAsync(["cloud", ...args], { from: "user" });
+    }
+    function seedCache() {
+        volumes.clear();
+        deleted.length = 0;
+        volumes.set("vol1", { id: "vol1", name: "n", sizeGb: 40, dataCenterId: "DC-1", type: "STANDARD" });
+        const journal = CloudJournal.open(getMoldeskPaths({ MOLDESK_HOME: home }));
+        const intent = journal.recordResourceIntent({ role: "volume" });
+        journal.recordResourceCreated(intent.intentId, "vol1");
+        journal.upsertCache({ accountScope: "acct", datacenterId: "DC-1", volumeId: "vol1", model: "boltz", modelVersion: "2.2.1", cacheKey: "k".repeat(64), layoutRevision: "1", manifestDigest: "m", cachePath: "/workspace/x", sizeBytes: null, checksumManifestDigest: null });
+        journal.close();
+    }
+    it("cache list reports empty and populated states", async () => {
+        await exec(true, "cache", "list");
+        expect(out.join("\n")).toContain("No retained caches.");
+        out.length = 0;
+        seedCache();
+        await exec(true, "cache", "list");
+        expect(out.join("\n")).toMatch(/boltz 2\.2\.1\s+PREPARING\s+DC-1\s+volume vol1 \(40 GB, billed\)/);
+    });
+    it("cache delete shows exactly what will go and deletes nothing when declined", async () => {
+        seedCache();
+        await exec(false, "cache", "delete", "boltz");
+        expect(err.join("\n")).toContain("permanently deletes 1 volume(s)");
+        expect(err.join("\n")).toContain("vol1  DC-1  40 GB");
+        expect(deleted).toEqual([]);
+        expect(process.exitCode).toBe(2);
+    });
+    it("cache delete --yes deletes the owned volume and confirms", async () => {
+        seedCache();
+        await exec(false, "cache", "delete", "boltz", "--yes");
+        expect(out.join("\n")).toContain("Deleted volume vol1.");
+        expect(deleted).toEqual(["vol1"]);
+        expect(process.exitCode).toBeUndefined();
+    });
+    it("cache delete for a model with no cache is a no-op", async () => {
+        await exec(true, "cache", "delete", "unknown-model");
+        expect(out.join("\n")).toContain("No retained cache for unknown-model.");
+    });
+    it("recover rejects an unknown run with a clear code", async () => {
+        await exec(true, "recover", "2026-01-01T00-00-00-000Z-00000000-0000-0000-0000-000000000000", "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ status: "error", code: "CLOUD_RUN_UNKNOWN" });
+        expect(process.exitCode).toBe(2);
+    });
+});
+describe("cloudExitCode", () => {
+    it("maps cloud error codes and defaults to 10", () => {
+        expect(cloudExitCode(new MoldeskError({ code: "CLOUD_CAPACITY_UNAVAILABLE", message: "x" }))).toBe(12);
+        expect(cloudExitCode(new MoldeskError({ code: "CREDENTIAL_INVALID", message: "x" }))).toBe(2);
+        expect(cloudExitCode(new Error("boom"))).toBe(10);
+    });
+});

package/dist/commands/run-cloud.d.ts

@@ -0,0 +1,30 @@
+import { type CloudQuote, type CloudRunDeps } from "@moldesk/core";
+export interface CloudRunFlags {
+    compute: string;
+    cachePolicy?: string;
+    gpu?: string;
+    datacenter?: string;
+    maxBudget?: string;
+    maxLifetime?: string;
+    yes?: boolean;
+    dryRun?: boolean;
+    acceptLifetimeRisk?: boolean;
+    acceptStorageCharges?: boolean;
+    output?: string;
+    runtime?: string;
+    param: Record<string, string>;
+    json?: boolean;
+    visualize?: boolean;
+}
+export interface CloudRunHooks {
+    /** Injected for tests; production resolves Runpod wiring from the credential store. */
+    deps?: () => Promise<CloudRunDeps>;
+    confirm?: (question: string) => Promise<boolean>;
+    interactive?: boolean;
+}
+/** Printed first and again at the prompt: there is no independent shutdown service. */
+export declare function formatWarnings(quote: CloudQuote): string;
+export declare function formatQuote(quote: CloudQuote): string;
+/** Rejects cloud-only flags on a local run, before anything happens. */
+export declare function assertNoCloudFlagsForLocal(flags: Partial<CloudRunFlags>): void;
+export declare function runCloudCommand(model: string, input: string, flags: CloudRunFlags, hooks?: CloudRunHooks): Promise<void>;

package/dist/commands/run-cloud.js

@@ -0,0 +1,201 @@
+import { pathToFileURL } from "node:url";
+import { MoldeskError, createRunpodCloudDeps, planCloudRun, runModel, } from "@moldesk/core";
+import { confirm } from "../utils/confirm.js";
+import { cloudExitCode, cloudExitCodeForCode } from "./cloud.js";
+function usage(code, message, remediation) {
+    return new MoldeskError({ code, message, remediation });
+}
+/** Printed first and again at the prompt: there is no independent shutdown service. */
+export function formatWarnings(quote) {
+    const bar = "!".repeat(72);
+    return [bar, "WARNING: READ BEFORE APPROVING", ...quote.warnings.flatMap((warning) => ["", warning.text]), "", bar].join("\n");
+}
+export function formatQuote(quote) {
+    const money = (value) => `$${value.toFixed(value < 1 ? 4 : 2)}`.replace(/\.?0+$/, (zeros) => (zeros.includes(".") ? "" : zeros));
+    const lines = [
+        formatWarnings(quote),
+        "",
+        `Cloud quote (${quote.provider}, prices as of ${quote.retrievedAt})`,
+        `  Model:        ${quote.model} ${quote.modelVersion}`,
+        `  GPU:          ${quote.gpu.name} (${quote.gpu.memoryGb} GB) in ${quote.datacenterId} at ${money(quote.gpu.priceUsdPerHour)}/h`,
+        ...(quote.cpu ? [`  Prep CPU:     ${quote.cpu.id} x${quote.cpu.vcpuCount} at ${money(quote.cpu.priceUsdPerHour)}/h (asset preparation only)`] : []),
+        `  Cache policy: ${quote.cachePolicy}`,
+        `  Limits:       lifetime ${quote.maxLifetimeSeconds}s, budget ${money(quote.maxBudgetUsd)}`,
+        `  Compute:      worst case ${money(quote.cost.worstCaseComputeUsd)} (hourly rate x lifetime limit; a ceiling for this estimate, not a provider-enforced spend cap)`,
+        `  Temp storage: ${quote.cost.temporaryStorage.worstCaseUsd === null ? `container disk ${quote.cost.temporaryStorage.diskGb} GB x ${quote.cost.temporaryStorage.machines} machine(s): cost unknown (rate not published)` : `container disk worst case ${money(quote.cost.temporaryStorage.worstCaseUsd)}`}`,
+        `  Retained:     ${quote.cost.recurringStorage.recurring ? `${quote.cost.recurringStorage.volumeGb} GB network volume kept until you delete it; ${quote.cost.recurringStorage.usdPerMonth === null ? "monthly cost unknown (rate not published)" : `about ${money(quote.cost.recurringStorage.usdPerMonth)}/month`}` : "nothing is kept after the run"}`,
+        `  Budget:       ${money(quote.maxBudgetUsd)} is checked against ${money(quote.cost.worstCaseBudgetedUsd)}`,
+        `    counts:     ${quote.budgetCoverage.counted.join("; ")}`,
+        `    NOT counted: ${quote.budgetCoverage.notCounted.join("; ")}`,
+        ...(quote.budgetCoverage.unknown.length > 0 ? [`    unknown:    ${quote.budgetCoverage.unknown.join("; ")}`] : []),
+        `  Timing:       no measured estimate available`,
+        `  Upload:       ${quote.upload.files} file(s), ${quote.upload.bytes} bytes`,
+        ...quote.disclosures.map((line) => `  - ${line}`),
+    ];
+    return lines.join("\n");
+}
+function parseBudget(raw) {
+    const value = Number(raw);
+    if (raw === undefined || !Number.isFinite(value) || value <= 0)
+        throw usage("CLOUD_BUDGET_REQUIRED", "A positive --max-budget (USD) is required.", "Pass --max-budget <usd>.");
+    return value;
+}
+function parseLifetime(raw) {
+    const value = Number(raw);
+    if (raw === undefined || !Number.isInteger(value) || value <= 0)
+        throw usage("CLOUD_LIFETIME_REQUIRED", "A positive integer --max-lifetime (seconds) is required.", "Pass --max-lifetime <seconds>.");
+    return value;
+}
+/** Rejects cloud-only flags on a local run, before anything happens. */
+export function assertNoCloudFlagsForLocal(flags) {
+    const used = [
+        ["--cache-policy", flags.cachePolicy],
+        ["--gpu", flags.gpu],
+        ["--datacenter", flags.datacenter],
+        ["--max-budget", flags.maxBudget],
+        ["--max-lifetime", flags.maxLifetime],
+    ].filter(([, value]) => value !== undefined);
+    if (flags.yes || flags.dryRun || flags.acceptLifetimeRisk || flags.acceptStorageCharges)
+        used.push(["--yes/--dry-run/--accept-*", "set"]);
+    if (used.length > 0) {
+        throw usage("CLOUD_OPTIONS_WITHOUT_CLOUD", `${used.map(([name]) => name).join(", ")} only apply with --compute runpod.`, "Add --compute runpod, or remove those options.");
+    }
+}
+export async function runCloudCommand(model, input, flags, hooks = {}) {
+    const out = (value) => console.log(JSON.stringify(value, null, 2));
+    try {
+        if (flags.compute !== "runpod")
+            throw usage("CLOUD_OPTIONS_REQUIRED", `Unsupported --compute "${flags.compute}".`, "Expected local|runpod.");
+        if (flags.runtime === "docker")
+            throw usage("CLOUD_RUNTIME_UNSUPPORTED", "The docker runtime is not supported for cloud execution.", "Use the python runtime.");
+        if (flags.cachePolicy !== "ephemeral" && flags.cachePolicy !== "persistent") {
+            throw usage("CLOUD_OPTIONS_REQUIRED", "--cache-policy ephemeral|persistent is required for cloud runs.", "Choose ephemeral (nothing retained) or persistent (a billed volume is kept).");
+        }
+        const cachePolicy = flags.cachePolicy;
+        const quoteOptions = {
+            cachePolicy,
+            ...(flags.gpu ? { gpuId: flags.gpu } : {}),
+            ...(flags.datacenter ? { datacenterId: flags.datacenter } : {}),
+            maxBudgetUsd: parseBudget(flags.maxBudget),
+            maxLifetimeSeconds: parseLifetime(flags.maxLifetime),
+        };
+        const deps = await (hooks.deps ?? (() => createRunpodCloudDeps()))();
+        const plan = await planCloudRun(model, input, { params: flags.param, cloud: quoteOptions }, deps);
+        if (flags.json) {
+            if (flags.dryRun)
+                return out({ status: "quote", quote: plan.quote });
+        }
+        else {
+            console.error(formatQuote(plan.quote));
+            if (flags.dryRun)
+                return void console.error("\nDry run: nothing was uploaded or provisioned.");
+        }
+        const interactive = hooks.interactive ?? (process.stdin.isTTY === true);
+        const ask = hooks.confirm ?? ((question) => confirm(question));
+        const canPrompt = interactive || hooks.confirm !== undefined;
+        // Each warning needs its own explicit acknowledgment: a flag, or an answered prompt. `--yes` alone never counts.
+        const acknowledged = [];
+        for (const warning of plan.quote.warnings) {
+            const flagged = warning.id === "lifetime-risk" ? flags.acceptLifetimeRisk === true : flags.acceptStorageCharges === true;
+            if (flagged) {
+                acknowledged.push(warning.id);
+                continue;
+            }
+            if (!canPrompt) {
+                throw usage("CLOUD_ACKNOWLEDGMENT_REQUIRED", `You must acknowledge: ${warning.text}`, `Re-run with ${warning.id === "lifetime-risk" ? "--accept-lifetime-risk" : "--accept-storage-charges"} (and --yes) to accept this risk without a terminal.`);
+            }
+            console.error(`\n${warning.text}`);
+            if (!(await ask("Do you understand and accept this risk?"))) {
+                if (flags.json)
+                    out({ status: "declined", quoteId: plan.quote.id, reason: `warning not acknowledged: ${warning.id}` });
+                else
+                    console.error("Not acknowledged. Nothing was uploaded or provisioned.");
+                process.exitCode = 2;
+                return;
+            }
+            acknowledged.push(warning.id);
+        }
+        let approved = flags.yes === true;
+        if (!approved) {
+            if (!canPrompt) {
+                throw usage("CLOUD_APPROVAL_MISMATCH", "This quote needs your approval, and no terminal is attached.", "Review it with --dry-run, then re-run with --yes to approve exactly this quote.");
+            }
+            approved = await ask("Approve this quote and start the cloud run?");
+            if (!approved) {
+                if (flags.json)
+                    out({ status: "declined", quoteId: plan.quote.id });
+                else
+                    console.error("Not approved. Nothing was uploaded or provisioned.");
+                process.exitCode = 2;
+                return;
+            }
+        }
+        const controller = new AbortController();
+        const onSignal = () => controller.abort();
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+        let result;
+        try {
+            result = await runModel(model, input, {
+                compute: "runpod",
+                params: flags.param,
+                outputDir: flags.output,
+                visualize: flags.visualize,
+                signal: controller.signal,
+                cloudDeps: deps,
+                cloud: { ...quoteOptions, quote: plan.quote, approval: { quoteId: plan.quote.id, approvedAt: new Date().toISOString(), acknowledged } },
+                onLog: flags.json ? undefined : (stream, chunk) => (stream === "stdout" ? process.stdout : process.stderr).write(chunk),
+                onProgress: flags.json ? undefined : (event) => console.error(`[${event.stage}]${event.message ? ` ${event.message}` : ""}`),
+            });
+        }
+        finally {
+            process.removeListener("SIGINT", onSignal);
+            process.removeListener("SIGTERM", onSignal);
+        }
+        if (flags.json) {
+            out({ model, ...result });
+        }
+        else {
+            console.log(`${result.record.model}: ${result.status}.`);
+            for (const output of result.record.outputs)
+                console.log(`  ${output.id}: ${output.path}`);
+            for (const artifact of result.record.artifacts ?? []) {
+                console.log(`  report: ${artifact.path}`);
+                console.log(`  Open in your browser: ${pathToFileURL(artifact.path).href}`);
+            }
+            for (const warning of result.record.warnings ?? [])
+                console.error(`  Warning (${warning.code}): ${warning.message}`);
+            if (result.record.error)
+                console.error(`  ${result.record.error.code}: ${result.record.error.message}`);
+            if (result.exportError)
+                console.error(`  --output copy failed: ${result.exportError.message}`);
+            if (result.record.compute?.hardware)
+                console.log(`  Ran on: ${result.record.compute.hardware.name} (${result.record.compute.datacenterId})`);
+            console.log(`  Run directory: ${result.record.command.cwd}`);
+            console.log(`  Logs: ${result.record.logs.stdout} and ${result.record.logs.stderr}`);
+        }
+        if (result.cleanupPending) {
+            const ids = result.cleanupPending.resources.map((resource) => `${resource.role} ${resource.providerId}`).join(", ");
+            console.error(`CLOUD_CLEANUP_PENDING: these paid resources could not be confirmed deleted: ${ids}.`);
+            console.error(`Run \`moldesk cloud recover ${result.record.id}\` and check \`moldesk cloud resources\`.`);
+            process.exitCode = 13;
+        }
+        else if (result.status === "cancelled")
+            process.exitCode = 8;
+        else if (result.status === "failed" || result.exportError)
+            process.exitCode = cloudExitCodeForCode(result.record.error?.code) ?? 7;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof MoldeskError ? error.code : undefined;
+        const remediation = error instanceof MoldeskError ? error.remediation : undefined;
+        if (flags.json)
+            out({ model, status: "error", message, code, remediation });
+        else {
+            console.error(message);
+            if (remediation)
+                console.error(remediation);
+        }
+        process.exitCode = cloudExitCode(error);
+    }
+}

package/dist/commands/run-cloud.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/run-cloud.test.js

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+import { getMoldeskPaths, parseManifest } from "@moldesk/core";
+import { registerRunCommand } from "./run.js";
+import { formatQuote } from "./run-cloud.js";
+const DIGEST = "a".repeat(64);
+let home;
+let out;
+let err;
+beforeEach(() => {
+    home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk cli run cloud "));
+    out = [];
+    err = [];
+    vi.spyOn(console, "log").mockImplementation((...a) => void out.push(a.join(" ")));
+    vi.spyOn(console, "error").mockImplementation((...a) => void err.push(a.join(" ")));
+    process.exitCode = undefined;
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    process.exitCode = undefined;
+    fs.rmSync(home, { recursive: true, force: true });
+});
+const manifest = () => parseManifest({
+    schemaVersion: 1,
+    name: "fake-model",
+    displayName: "Fake",
+    modelVersion: "1.0.0",
+    adapterVersion: "0.1.0",
+    description: "t",
+    category: "other",
+    status: "planned",
+    runtimes: [{ kind: "python", python: "3.11", installer: "uv", platforms: ["linux-x64"], requirements: [{ name: "torch" }] }],
+    hardware: { platforms: ["linux-x64"] },
+    input: { formats: [".txt"], required: true },
+    outputs: [{ id: "result", glob: "*.out", required: true }],
+    cloud: { schemaVersion: 1, platform: "linux-x64", images: { gpu: `r.example/g@sha256:${DIGEST}`, cpu: `r.example/c@sha256:${DIGEST}` }, minVramGb: 24, minRamGb: 32, ephemeralDiskGb: 40, volumeGb: 40, assetLayoutRevision: "1", cpuAssetPreparation: true },
+}, "x/manifest.yaml");
+const adapter = {
+    modelName: "fake-model",
+    params: [],
+    async validateInput() { },
+    async installPlan() {
+        return { steps: [] };
+    },
+    async command() {
+        throw new Error("client never builds a remote command");
+    },
+    async collectOutputs(context) {
+        return fs.readdirSync(context.outputDir).filter((n) => n.endsWith(".out")).map((n) => ({ id: "result", path: path.join(context.outputDir, n) }));
+    },
+    async verifyInstallation() {
+        return { passed: true };
+    },
+};
+function fakeDeps(opts = {}) {
+    const pods = new Map();
+    const calls = { start: 0, upload: 0 };
+    const provider = {
+        name: "runpod",
+        getCatalog: async () => ({
+            retrievedAt: "2026-10-13T12:00:00.000Z",
+            gpus: [{ id: "a40", name: "A40", memoryGb: 48, priceUsdPerHour: 0.6, availability: "LOW", dataCenters: [{ id: "DC-1", availability: "LOW" }], cudaVersions: [] }],
+            cpus: [{ id: "cpu3c", name: "c", priceUsdPerVcpuHour: 0.03, ramGbPerVcpu: 2, minVcpu: 2, maxVcpu: 32 }],
+            dataCenters: [{ id: "DC-1", region: "EU", networkVolumeTypes: ["STANDARD"] }],
+        }),
+        listPods: async () => [...pods.values()],
+        getPod: async (id) => pods.get(id) ?? null,
+        terminatePod: async (id) => {
+            if (opts.terminateFails)
+                throw new Error("down");
+            pods.delete(id);
+            return { id, alreadyAbsent: false };
+        },
+    };
+    const backend = {
+        async start(job, context) {
+            calls.start += 1;
+            const intent = context.ledger.beginCreate("gpu");
+            pods.set("pod1", { id: "pod1", name: intent.name, status: "RUNNING" });
+            context.ledger.created(intent.intentId, "pod1");
+            return { version: 1, runId: job.runId, podId: "pod1", endpoint: "https://w" };
+        },
+        async observe() {
+            return { stage: "running", state: "succeeded", exitCode: 0, logs: { cursor: 1, stdout: "hello from the worker\n", stderr: "note\n" }, runtime: { dependencyFreeze: [], gpu: { name: "A40" } } };
+        },
+        async cancel() { },
+        async collect(_h, dir) {
+            fs.writeFileSync(path.join(dir, "answer.out"), "ok");
+            return { version: 1, files: [] };
+        },
+        async release() { },
+    };
+    const deps = { provider, backend, paths: getMoldeskPaths({ MOLDESK_HOME: home }), accountScope: "acct", resolveModel: () => ({ manifest: manifest(), adapter }), sleep: async () => undefined, pollIntervalMs: 1, cleanupAttempts: 1 };
+    return { deps, calls, pods };
+}
+async function run(hooks, ...args) {
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program, hooks);
+    await program.parseAsync(["run", "fake-model", inputPath(), ...args], { from: "user" });
+}
+function inputPath() {
+    const file = path.join(home, "in.txt");
+    fs.writeFileSync(file, "job");
+    return file;
+}
+const base = ["--compute", "runpod", "--cache-policy", "ephemeral", "--max-budget", "5", "--max-lifetime", "3600"];
+const accept = ["--accept-lifetime-risk"];
+const WARNING = "If MoleculeDesk closes or loses connection, your Runpod Pod may keep running and charging. Automatic shutdown is not guaranteed. Check your Runpod dashboard and terminate any remaining Pod.";
+describe("moldesk run --compute runpod", () => {
+    it("rejects cloud-only flags on a local run", async () => {
+        await run({}, "--max-budget", "5");
+        expect(err.join("\n")).toMatch(/only apply with --compute runpod/);
+        expect(process.exitCode).toBe(2);
+    });
+    it("requires a cache policy, a budget and a lifetime before touching the provider", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps }, "--compute", "runpod", "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ code: "CLOUD_OPTIONS_REQUIRED" });
+        out.length = 0;
+        await run({ deps: async () => f.deps }, "--compute", "runpod", "--cache-policy", "ephemeral", "--max-lifetime", "60", "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ code: "CLOUD_BUDGET_REQUIRED" });
+        out.length = 0;
+        await run({ deps: async () => f.deps }, "--compute", "runpod", "--cache-policy", "ephemeral", "--max-budget", "1", "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ code: "CLOUD_LIFETIME_REQUIRED" });
+        expect(process.exitCode).toBe(2);
+        expect(f.calls.start).toBe(0);
+    });
+    it("rejects the docker runtime and unsupported models before anything is provisioned", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps }, ...base, "--runtime", "docker");
+        expect(process.exitCode).toBe(2);
+        process.exitCode = undefined;
+        const unsupported = { ...f.deps, resolveModel: () => ({ manifest: { ...manifest(), cloud: undefined }, adapter }) };
+        await run({ deps: async () => unsupported }, ...base, "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ code: "CLOUD_MODEL_UNSUPPORTED" });
+        expect(process.exitCode).toBe(4);
+    });
+    it("--dry-run prints the quote and provisions nothing", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps }, ...base, "--dry-run");
+        expect(err.join("\n")).toContain("Cloud quote (runpod");
+        expect(err.join("\n")).toContain("Dry run: nothing was uploaded or provisioned.");
+        expect(f.calls).toEqual({ start: 0, upload: 0 });
+        expect(process.exitCode).toBeUndefined();
+        expect(fs.existsSync(getMoldeskPaths({ MOLDESK_HOME: home }).runs)).toBe(false);
+    });
+    it("--dry-run --json emits a machine-readable quote on stdout only", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps }, ...base, "--dry-run", "--json");
+        const parsed = JSON.parse(out.join("\n"));
+        expect(parsed.status).toBe("quote");
+        expect(parsed.quote).toMatchObject({ provider: "runpod", cachePolicy: "ephemeral", gpu: { id: "a40" } });
+        expect(err).toEqual([]);
+    });
+    it("needs --yes without a terminal, and a declined prompt provisions nothing", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps, interactive: false }, ...base, ...accept);
+        expect(err.join("\n")).toMatch(/needs your approval, and no terminal is attached/);
+        expect(process.exitCode).toBe(14);
+        process.exitCode = undefined;
+        err.length = 0;
+        await run({ deps: async () => f.deps, confirm: async (q) => !q.startsWith("Approve") }, ...base, ...accept);
+        expect(err.join("\n")).toContain("Not approved");
+        expect(process.exitCode).toBe(2);
+        expect(f.calls.start).toBe(0);
+    });
+    it("shows the exact shutdown warning prominently, before the quote body and before any prompt", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps }, ...base, "--dry-run");
+        const lines = err.join("\n").split("\n");
+        expect(lines[0]).toMatch(/^!{40,}$/);
+        expect(lines[1]).toBe("WARNING: READ BEFORE APPROVING");
+        expect(err.join("\n")).toContain(WARNING);
+        expect(err.join("\n").indexOf(WARNING)).toBeLessThan(err.join("\n").indexOf("Cloud quote (runpod"));
+    });
+    it("does not accept --yes as acknowledgment of the shutdown risk", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps, interactive: false }, ...base, "--yes", "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ status: "error", code: "CLOUD_ACKNOWLEDGMENT_REQUIRED" });
+        expect(JSON.parse(out.join("\n")).message).toContain(WARNING);
+        expect(process.exitCode).toBe(14);
+        expect(f.calls.start).toBe(0);
+    });
+    it("asks for the risk acknowledgment explicitly in an interactive session, then for approval", async () => {
+        const f = fakeDeps();
+        const asked = [];
+        await run({ deps: async () => f.deps, confirm: async (q) => (asked.push(q), true) }, ...base);
+        expect(asked).toEqual(["Do you understand and accept this risk?", "Approve this quote and start the cloud run?"]);
+        expect(err.join("\n")).toContain(WARNING);
+        expect(out.join("\n")).toContain("fake-model: succeeded.");
+        expect(f.calls.start).toBe(1);
+    });
+    it("provisions nothing when the risk is not acknowledged", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps, confirm: async () => false }, ...base);
+        expect(err.join("\n")).toContain("Not acknowledged. Nothing was uploaded or provisioned.");
+        expect(process.exitCode).toBe(2);
+        expect(f.calls.start).toBe(0);
+    });
+    it("persistent caching also requires acknowledging that storage charges continue until deleted", async () => {
+        const f = fakeDeps();
+        const persistent = ["--compute", "runpod", "--cache-policy", "persistent", "--max-budget", "5", "--max-lifetime", "3600"];
+        await run({ deps: async () => f.deps, interactive: false }, ...persistent, "--yes", ...accept, "--json");
+        expect(JSON.parse(out.join("\n"))).toMatchObject({ code: "CLOUD_ACKNOWLEDGMENT_REQUIRED" });
+        expect(JSON.parse(out.join("\n")).message).toMatch(/Storage charges continue until you delete it/);
+        expect(f.calls.start).toBe(0);
+        out.length = 0;
+        err.length = 0;
+        process.exitCode = undefined;
+        const asked = [];
+        await run({ deps: async () => f.deps, confirm: async (q) => (asked.push(q), false) }, ...persistent, "--dry-run");
+        expect(err.join("\n")).toMatch(/Storage charges continue until you delete it/);
+        await run({ deps: async () => f.deps, confirm: async (q) => (asked.push(q), q.startsWith("Do you understand")) }, ...persistent);
+        expect(asked.filter((q) => q.startsWith("Do you understand"))).toHaveLength(2);
+    });
+    it("runs end to end after approval and reports where it ran", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps, confirm: async () => true }, ...base);
+        expect(out.join("\n")).toContain("fake-model: succeeded.");
+        expect(out.join("\n")).toContain("Ran on: A40 (DC-1)");
+        expect(process.exitCode).toBeUndefined();
+        expect(f.pods.size).toBe(0);
+        expect(f.calls.start).toBe(1);
+    });
+    it("--yes approves exactly the quote shown, with JSON on stdout", async () => {
+        const f = fakeDeps();
+        await run({ deps: async () => f.deps }, ...base, ...accept, "--yes", "--json");
+        const parsed = JSON.parse(out.join("\n"));
+        expect(parsed).toMatchObject({ status: "succeeded", record: { compute: { provider: "runpod", cleanup: "confirmed", acknowledgedRisks: ["lifetime-risk"] } } });
+        // Logs are persisted for --json runs too, and survive the machine being terminated.
+        expect(fs.readFileSync(parsed.record.logs.stdout, "utf8")).toBe("hello from the worker\n");
+        expect(fs.readFileSync(parsed.record.logs.stderr, "utf8")).toBe("note\n");
+        expect(f.pods.size).toBe(0);
+    });
+    it("exits 13 with exact resource ids and a recover hint when cleanup cannot be confirmed", async () => {
+        const f = fakeDeps({ terminateFails: true });
+        await run({ deps: async () => f.deps }, ...base, ...accept, "--yes");
+        expect(err.join("\n")).toMatch(/CLOUD_CLEANUP_PENDING: .*gpu pod1/);
+        expect(err.join("\n")).toMatch(/moldesk cloud recover /);
+        expect(process.exitCode).toBe(13);
+    });
+});
+describe("formatQuote", () => {
+    it("states ceilings, unknowns and retained storage plainly", async () => {
+        const f = fakeDeps();
+        const { planCloudRun } = await import("@moldesk/core");
+        const plan = await planCloudRun("fake-model", inputPath(), { cloud: { cachePolicy: "persistent", maxBudgetUsd: 5, maxLifetimeSeconds: 3600 } }, f.deps);
+        const text = formatQuote(plan.quote);
+        expect(text).toContain("not a provider-enforced spend cap");
+        expect(text).toContain("40 GB network volume kept until you delete it; monthly cost unknown (rate not published)");
+        expect(text).toContain("container disk 40 GB x 2 machine(s): cost unknown (rate not published)");
+        expect(text).toMatch(/NOT counted: .*container disk charges.*retained network volume storage/);
+        expect(text).toMatch(/unknown:\s+container disk rate is not published.*network volume rate is not published/);
+        expect(text).toContain("no measured estimate available");
+        expect(text).toContain("Prep CPU:");
+    });
+});

package/dist/commands/run.d.ts

@@ -1,2 +1,3 @@
 import type { Command } from "commander";
-export declare function registerRunCommand(program: Command): void;
+import { type CloudRunHooks } from "./run-cloud.js";
+export declare function registerRunCommand(program: Command, cloudHooks?: CloudRunHooks): void;

package/dist/commands/run.js

@@ -1,5 +1,6 @@
 import { pathToFileURL } from "node:url";
 import { MoldeskError, runModel } from "@moldesk/core";
+import { assertNoCloudFlagsForLocal, runCloudCommand } from "./run-cloud.js";
 function parseRuntime(value) {
     if (value === "python" || value === "docker")
         return value;
@@ -34,7 +35,7 @@ function exitCodeFor(error) {
         return EXIT_CODES[error.code];
     return 10;
 }
-export function registerRunCommand(program) {
+export function registerRunCommand(program, cloudHooks = {}) {
     program
         .command("run <model> <input>")
         .description("Run a model against an input file")
@@ -43,7 +44,29 @@ export function registerRunCommand(program) {
         .option("--param <key=value>", "set a model parameter (repeatable)", collectParam, {})
         .option("--no-visualize", "skip creating the offline molecular report")
         .option("--json", "print the run result as JSON")
+        .option("--compute <kind>", "where to run: local (default) or runpod", "local")
+        .option("--cache-policy <policy>", "cloud: ephemeral (nothing retained) or persistent (a billed volume is kept)")
+        .option("--gpu <id>", "cloud: GPU type id (default: cheapest eligible)")
+        .option("--datacenter <id>", "cloud: datacenter id")
+        .option("--max-budget <usd>", "cloud: maximum budget in USD (a guard on the quote, not a provider cap)")
+        .option("--max-lifetime <seconds>", "cloud: lifetime limit in seconds, enforced by MoleculeDesk only while it is running and connected (shutdown is not guaranteed)")
+        .option("--yes", "cloud: approve exactly the quote shown (required without a terminal)")
+        .option("--accept-lifetime-risk", "cloud: acknowledge that machines may keep running and charging if MoleculeDesk closes or disconnects")
+        .option("--accept-storage-charges", "cloud: acknowledge that a persistent cache keeps billing until you delete it")
+        .option("--dry-run", "cloud: print the quote and exit without uploading or provisioning")
         .action(async (model, input, options) => {
+        if (options.compute !== "local") {
+            await runCloudCommand(model, input, options, cloudHooks);
+            return;
+        }
+        try {
+            assertNoCloudFlagsForLocal(options);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 2;
+            return;
+        }
         const runtime = options.runtime ? parseRuntime(options.runtime) : undefined;
         const controller = new AbortController();
         const onSignal = () => controller.abort();

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { VERSION } from "@moldesk/core";
+import { registerCloudCommand } from "./commands/cloud.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerListCommand } from "./commands/list.js";
 import { registerInstallCommand } from "./commands/install.js";
@@ -19,5 +20,6 @@ registerInstallCommand(program);
 registerUninstallCommand(program);
 registerRunCommand(program);
 registerViewCommand(program);
+registerCloudCommand(program);
 registerVisualizerCommand(program);
 program.parse();

package/dist/utils/confirm.d.ts

@@ -0,0 +1,6 @@
+import type { Readable, Writable } from "node:stream";
+/** Asks a yes/no question on stderr (stdout stays machine-readable). Anything but y/yes declines. */
+export declare function confirm(question: string, io?: {
+    input?: Readable;
+    output?: Writable;
+}): Promise<boolean>;

package/dist/utils/confirm.js

@@ -0,0 +1,17 @@
+import readline from "node:readline";
+/** Asks a yes/no question on stderr (stdout stays machine-readable). Anything but y/yes declines. */
+export function confirm(question, io = {}) {
+    const rl = readline.createInterface({ input: io.input ?? process.stdin, output: io.output ?? process.stderr, terminal: false });
+    return new Promise((resolve) => {
+        let answered = false;
+        rl.question(`${question} [y/N] `, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+        rl.once("close", () => {
+            if (!answered)
+                resolve(false);
+        });
+    });
+}

package/dist/utils/secret-input.d.ts

@@ -0,0 +1,17 @@
+import type { Readable, Writable } from "node:stream";
+interface TtyInput extends Readable {
+    isTTY?: boolean;
+    setRawMode?: (mode: boolean) => unknown;
+}
+export interface ReadSecretOptions {
+    input: TtyInput;
+    /** Prompt and newline go here (stderr), never the secret. */
+    output: Writable;
+    prompt: string;
+}
+/**
+ * Reads one secret without echoing it. On a terminal, characters are collected in raw mode and
+ * nothing is printed back. On a pipe, the first line is taken. The secret is never an argument.
+ */
+export declare function readSecret({ input, output, prompt }: ReadSecretOptions): Promise<string>;
+export {};

package/dist/utils/secret-input.js

@@ -0,0 +1,42 @@
+/**
+ * Reads one secret without echoing it. On a terminal, characters are collected in raw mode and
+ * nothing is printed back. On a pipe, the first line is taken. The secret is never an argument.
+ */
+export function readSecret({ input, output, prompt }) {
+    return new Promise((resolve, reject) => {
+        output.write(prompt);
+        let buffer = "";
+        const interactive = input.isTTY === true && typeof input.setRawMode === "function";
+        if (interactive)
+            input.setRawMode(true);
+        input.resume();
+        input.setEncoding?.("utf8");
+        const finish = (action) => {
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.removeListener("error", onError);
+            if (interactive)
+                input.setRawMode(false);
+            input.pause();
+            output.write("\n");
+            action();
+        };
+        const onEnd = () => finish(() => resolve(buffer.replace(/\r?\n.*$/s, "")));
+        const onError = (error) => finish(() => reject(error));
+        const onData = (chunk) => {
+            for (const char of chunk.toString()) {
+                if (char === "\u0003")
+                    return finish(() => reject(new Error("Cancelled.")));
+                if (char === "\r" || char === "\n")
+                    return finish(() => resolve(buffer));
+                if (interactive && (char === "\u007f" || char === "\b"))
+                    buffer = buffer.slice(0, -1);
+                else
+                    buffer += char;
+            }
+        };
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.on("error", onError);
+    });
+}

package/dist/utils/secret-input.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/secret-input.test.js

@@ -0,0 +1,43 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { readSecret } from "./secret-input.js";
+function tty() {
+    const input = new PassThrough();
+    input.isTTY = true;
+    input.raw = [];
+    input.setRawMode = (mode) => void input.raw.push(mode);
+    return input;
+}
+describe("readSecret", () => {
+    it("never echoes typed characters and restores raw mode (interactive)", async () => {
+        const input = tty();
+        const output = new PassThrough();
+        const written = [];
+        output.on("data", (chunk) => written.push(chunk.toString()));
+        const pending = readSecret({ input, output, prompt: "key: " });
+        input.write("abc");
+        input.write("\u007fd12345\r");
+        expect(await pending).toBe("abd12345");
+        expect(written.join("")).toBe("key: \n");
+        expect(input.raw).toEqual([true, false]);
+    });
+    it("rejects on Ctrl-C", async () => {
+        const input = tty();
+        const pending = readSecret({ input, output: new PassThrough(), prompt: "k: " });
+        input.write("ab\u0003");
+        await expect(pending).rejects.toThrow("Cancelled.");
+        expect(input.raw).toEqual([true, false]);
+    });
+    it("takes the first line from a pipe and ignores the rest", async () => {
+        const input = new PassThrough();
+        const pending = readSecret({ input, output: new PassThrough(), prompt: "k: " });
+        input.end("first-line-key\nsecond\n");
+        expect(await pending).toBe("first-line-key");
+    });
+    it("returns what was received when a pipe ends without a newline", async () => {
+        const input = new PassThrough();
+        const pending = readSecret({ input, output: new PassThrough(), prompt: "k: " });
+        input.end("only-key");
+        expect(await pending).toBe("only-key");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldesk/cli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "MoleculeDesk CLI — install and run computational biology models",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
   ],
   "dependencies": {
     "commander": "^12.1.0",
-    "@moldesk/core": "0.0.5"
+    "@moldesk/core": "0.0.6"
   },
   "devDependencies": {
     "typescript": "^5.6.3",