@cargo-ai/cli 1.0.15 → 1.0.17

package/README.md

@@ -112,7 +112,8 @@ cargo-ai orchestration workflow --help
 | **system-of-record**     | System of record, client, logs                             | `cargo-ai system-of-record sor list`, `cargo-ai system-of-record log list --payload '{}'`                                     |
 | **user-management**      | Current user (no workspace context)                        | `cargo-ai user-management user get-current`                                                                                   |
 | **ai**                   | AI templates, agents, releases, chats, MCP, files          | `cargo-ai ai template list`, `cargo-ai ai agent list`, `cargo-ai ai file list`                                                |
-| **context**              | Context repository, files, and skills                      | `cargo-ai context skill list`, `cargo-ai context skill get --slug <slug>`, `cargo-ai context file list`                       |
+| **context**              | Context repository, runtime sandbox, and knowledge graph   | `cargo-ai context repository get`, `cargo-ai context runtime browse --path <path>`, `cargo-ai context graph get`              |
+| **hosting**              | Cargo Hosting apps (Vite SPAs), workers, and deployments   | `cargo-ai hosting app list`, `cargo-ai hosting worker list`, `cargo-ai hosting deployment list --payload '{}'`                |
 
 Commands that accept complex payloads use a `--payload <json>` option (e.g. `cargo-ai orchestration play create --payload '{"name":"My Play",...}'`). Use `--help` on any subcommand for options.
 

package/build/commands/connection/customIntegration.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerCustomIntegrationCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=customIntegration.d.ts.map

package/build/commands/connection/customIntegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customIntegration.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/customIntegration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAqJN"}

package/build/commands/connection/customIntegration.js

@@ -0,0 +1,98 @@
+import { handleApiCall, outputJson } from "../runHandler.js";
+export function registerCustomIntegrationCommands(parent, getApi) {
+    const customIntegration = parent
+        .command("custom-integration")
+        .description("Manage custom integrations (external HTTP servers or worker-backed integrations)");
+    customIntegration
+        .command("list")
+        .description("List custom integrations in the current workspace")
+        .action(async () => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.connection.customIntegration.list());
+        outputJson(result);
+    });
+    customIntegration
+        .command("get <uuid>")
+        .description("Get a custom integration by UUID")
+        .action(async (uuid) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.connection.customIntegration.get({ uuid }));
+        outputJson(result);
+    });
+    customIntegration
+        .command("create")
+        .description("Register a custom integration (kind=external for an externally hosted server, kind=worker for a Cargo Hosting worker)")
+        .requiredOption("--kind <kind>", 'Integration kind: "external" or "worker"')
+        .option("--base-url <url>", "Base URL of the externally hosted integration server (required when --kind external)")
+        .option("--worker-uuid <uuid>", "UUID of the Cargo Hosting worker that backs the integration (required when --kind worker)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai connection custom-integration create --kind external --base-url https://abc123.ngrok.io
+  $ cargo-ai connection custom-integration create --kind worker --worker-uuid 11111111-2222-3333-4444-555555555555`)
+        .action(async (opts) => {
+        if (opts.kind !== "external" && opts.kind !== "worker") {
+            console.error(JSON.stringify({
+                error: `Invalid --kind "${opts.kind}". Expected "external" or "worker".`,
+            }));
+            process.exit(1);
+        }
+        if (opts.kind === "external" && opts.baseUrl === undefined) {
+            console.error(JSON.stringify({
+                error: "--base-url is required when --kind is external.",
+            }));
+            process.exit(1);
+        }
+        if (opts.kind === "worker" && opts.workerUuid === undefined) {
+            console.error(JSON.stringify({
+                error: "--worker-uuid is required when --kind is worker.",
+            }));
+            process.exit(1);
+        }
+        const api = getApi();
+        const result = await handleApiCall(() => opts.kind === "external"
+            ? api.connection.customIntegration.create({
+                kind: "external",
+                baseUrl: opts.baseUrl,
+            })
+            : api.connection.customIntegration.create({
+                kind: "worker",
+                workerUuid: opts.workerUuid,
+            }));
+        outputJson(result);
+    });
+    customIntegration
+        .command("update")
+        .description("Update a custom integration's base URL or worker (kind cannot change)")
+        .requiredOption("--uuid <uuid>", "Custom integration UUID")
+        .option("--base-url <url>", "New base URL (only valid when the integration was created with kind=external)")
+        .option("--worker-uuid <uuid>", "New worker UUID (only valid when the integration was created with kind=worker)")
+        .action(async (opts) => {
+        if (opts.baseUrl === undefined && opts.workerUuid === undefined) {
+            console.error(JSON.stringify({
+                error: "Provide at least one of --base-url or --worker-uuid.",
+            }));
+            process.exit(1);
+        }
+        if (opts.baseUrl !== undefined && opts.workerUuid !== undefined) {
+            console.error(JSON.stringify({
+                error: "--base-url and --worker-uuid are mutually exclusive.",
+            }));
+            process.exit(1);
+        }
+        const api = getApi();
+        const result = await handleApiCall(() => api.connection.customIntegration.update({
+            uuid: opts.uuid,
+            baseUrl: opts.baseUrl,
+            workerUuid: opts.workerUuid,
+        }));
+        outputJson(result);
+    });
+    customIntegration
+        .command("remove <uuid>")
+        .description("Remove a custom integration")
+        .action(async (uuid) => {
+        const api = getApi();
+        await handleApiCall(() => api.connection.customIntegration.remove(uuid));
+        outputJson({ ok: true });
+    });
+}

package/build/commands/connection/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAKxC,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAQN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAMxC,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CASN"}

package/build/commands/connection/index.js

@@ -1,4 +1,5 @@
 import { registerConnectorCommands } from "./connector.js";
+import { registerCustomIntegrationCommands } from "./customIntegration.js";
 import { registerIntegrationCommands } from "./integration.js";
 import { registerNativeIntegrationCommands } from "./nativeIntegration.js";
 export function registerConnectionCommands(parent, getApi) {
@@ -8,4 +9,5 @@ export function registerConnectionCommands(parent, getApi) {
     registerConnectorCommands(connection, getApi);
     registerIntegrationCommands(connection, getApi);
     registerNativeIntegrationCommands(connection, getApi);
+    registerCustomIntegrationCommands(connection, getApi);
 }

package/build/commands/context/{skill.d.ts → graph.d.ts}

@@ -1,4 +1,4 @@
 import type { Command } from "commander";
 import type { Api } from "../../api.js";
-export declare function registerSkillCommands(parent: Command, getApi: () => Api): void;
-//# sourceMappingURL=skill.d.ts.map
+export declare function registerGraphCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=graph.d.ts.map

package/build/commands/context/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/commands/context/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAeN"}

package/build/commands/context/graph.js

@@ -0,0 +1,14 @@
+import { handleApiCall, outputJson } from "../runHandler.js";
+export function registerGraphCommands(parent, getApi) {
+    const graph = parent
+        .command("graph")
+        .description("Inspect the context knowledge graph for the workspace");
+    graph
+        .command("get")
+        .description("Build (or load from cache) the knowledge graph of all markdown/MDX files in the context repo")
+        .action(async () => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.context.graph.get());
+        outputJson(result);
+    });
+}

package/build/commands/context/index.js

@@ -1,11 +1,11 @@
-import { registerFileCommands } from "./file.js";
+import { registerGraphCommands } from "./graph.js";
 import { registerRepositoryCommands } from "./repository.js";
-import { registerSkillCommands } from "./skill.js";
+import { registerRuntimeCommands } from "./runtime.js";
 export function registerContextCommands(parent, getApi) {
     const context = parent
         .command("context")
-        .description("Context repository, files, and skills");
+        .description("Context repository and runtime sandbox operations");
     registerRepositoryCommands(context, getApi);
-    registerFileCommands(context, getApi);
-    registerSkillCommands(context, getApi);
+    registerRuntimeCommands(context, getApi);
+    registerGraphCommands(context, getApi);
 }

package/build/commands/context/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../src/commands/context/repository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA8CN"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../src/commands/context/repository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAaN"}

package/build/commands/context/repository.js

@@ -1,4 +1,4 @@
-import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
+import { handleApiCall, outputJson } from "../runHandler.js";
 export function registerRepositoryCommands(parent, getApi) {
     const repository = parent
         .command("repository")
@@ -11,23 +11,4 @@ export function registerRepositoryCommands(parent, getApi) {
         const result = await handleApiCall(() => api.context.repository.get());
         outputJson(result);
     });
-    repository
-        .command("update")
-        .description("Update the context repository configuration")
-        .option("--source <json>", 'Repository source (JSON, e.g. {"kind":"managed"} or {"kind":"custom","connectorUuid":"..."})')
-        .option("--repository-owner <owner>", "GitHub owner (user or org)")
-        .option("--repository-name <name>", "GitHub repository name")
-        .option("--default-branch <branch>", "Default branch (e.g. main)")
-        .action(async (opts) => {
-        const api = getApi();
-        const result = await handleApiCall(() => api.context.repository.update({
-            source: opts.source !== undefined
-                ? parseJson(opts.source, "--source")
-                : undefined,
-            repositoryOwner: opts.repositoryOwner,
-            repositoryName: opts.repositoryName,
-            defaultBranch: opts.defaultBranch,
-        }));
-        outputJson(result);
-    });
 }

package/build/commands/context/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerRuntimeCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=runtime.d.ts.map

package/build/commands/context/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/commands/context/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAoJN"}

package/build/commands/context/runtime.js

@@ -0,0 +1,84 @@
+import { handleApiCall, outputJson } from "../runHandler.js";
+export function registerRuntimeCommands(parent, getApi) {
+    const runtime = parent
+        .command("runtime")
+        .description("Read, write, edit, browse, and execute against the workspace runtime sandbox");
+    runtime
+        .command("browse")
+        .description("List entries in the runtime sandbox")
+        .option("--path <path>", "Path to browse (omit to browse the root)")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.context.runtime.browse({ path: opts.path }));
+        outputJson(result);
+    });
+    runtime
+        .command("read")
+        .description("Read a file from the runtime sandbox")
+        .requiredOption("--path <path>", "Path to the file")
+        .option("--start-line <line>", "1-indexed inclusive start line (defaults to first line)")
+        .option("--end-line <line>", "1-indexed inclusive end line (defaults to last line)")
+        .action(async (opts) => {
+        const api = getApi();
+        const startLine = opts.startLine !== undefined ? Number(opts.startLine) : undefined;
+        const endLine = opts.endLine !== undefined ? Number(opts.endLine) : undefined;
+        const result = await handleApiCall(() => api.context.runtime.read({
+            path: opts.path,
+            startLine,
+            endLine,
+        }));
+        outputJson(result);
+    });
+    runtime
+        .command("write")
+        .description("Write a file in the runtime sandbox and push to the default branch")
+        .requiredOption("--path <path>", "Path to the file")
+        .requiredOption("--content <content>", "File content")
+        .option("--commit-message <message>", "Commit message override")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.context.runtime.write({
+            path: opts.path,
+            content: opts.content,
+            commitMessage: opts.commitMessage,
+        }));
+        outputJson(result);
+    });
+    runtime
+        .command("edit")
+        .description("Replace occurrences of oldString with newString and push to the default branch")
+        .requiredOption("--path <path>", "Path to the file")
+        .requiredOption("--old-string <old>", "Exact substring to replace (must occur once unless --replace-all is set)")
+        .requiredOption("--new-string <new>", "Replacement string (may be empty to delete the match). Must differ from --old-string.")
+        .option("--replace-all", "Replace every occurrence of --old-string instead of requiring a single match")
+        .option("--commit-message <message>", "Commit message override")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.context.runtime.edit({
+            path: opts.path,
+            oldString: opts.oldString,
+            newString: opts.newString,
+            replaceAll: opts.replaceAll,
+            commitMessage: opts.commitMessage,
+        }));
+        outputJson(result);
+    });
+    runtime
+        .command("execute")
+        .description("Run a shell command in the runtime sandbox. Tracked working-tree changes are auto-committed to the workspace's default branch (gitignored paths are skipped). Use --commit-message to override the auto-commit subject.")
+        .requiredOption("--command <command>", "Shell command to run")
+        .option("--args <json>", "JSON array of arguments")
+        .option("--commit-message <message>", "Override for the auto-commit subject (defaults to `context(runtime): execute <command>`)")
+        .action(async (opts) => {
+        const api = getApi();
+        const args = opts.args !== undefined
+            ? JSON.parse(opts.args)
+            : undefined;
+        const result = await handleApiCall(() => api.context.runtime.execute({
+            command: opts.command,
+            args,
+            commitMessage: opts.commitMessage,
+        }));
+        outputJson(result);
+    });
+}

package/build/commands/{orchestration/log.d.ts → hosting/app.d.ts}

@@ -1,4 +1,4 @@
 import type { Command } from "commander";
 import type { Api } from "../../api.js";
-export declare function registerLogCommands(parent: Command, getApi: () => Api): void;
-//# sourceMappingURL=log.d.ts.map
+export declare function registerAppCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=app.d.ts.map

package/build/commands/hosting/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/commands/hosting/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAMxC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAsO5E"}

package/build/commands/hosting/app.js

@@ -0,0 +1,190 @@
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { handleApiCall, outputJson } from "../runHandler.js";
+import { copyDirectory, listTemplates } from "./templateUtils.js";
+const require = createRequire(import.meta.url);
+export function registerAppCommands(parent, getApi) {
+    const app = parent
+        .command("app")
+        .description("Manage Cargo Hosting apps (Vite SPAs served on *.cargo.app)");
+    app
+        .command("list")
+        .description("List apps in the current workspace")
+        .option("--folder-uuid <uuid>", "Filter by folder UUID")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.app.list({
+            folderUuid: opts.folderUuid,
+        }));
+        outputJson(result);
+    });
+    app
+        .command("get <uuid>")
+        .description("Show details of a single app")
+        .action(async (uuid) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.app.get(uuid));
+        outputJson(result);
+    });
+    app
+        .command("create")
+        .description("Create a new app slot")
+        .requiredOption("--name <name>", "Display name for the app")
+        .requiredOption("--slug <slug>", "URL slug (must be globally unique within the hosting domain)")
+        .option("--folder-uuid <uuid>", "Optional folder UUID")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.app.create({
+            name: opts.name,
+            slug: opts.slug,
+            folderUuid: opts.folderUuid,
+        }));
+        outputJson(result);
+    });
+    app
+        .command("update")
+        .description("Update an existing app (name, folder)")
+        .requiredOption("--uuid <uuid>", "App UUID")
+        .option("--name <name>", "New display name")
+        .option("--folder-uuid <uuid>", "New folder UUID (pass 'null' to move to the workspace root)")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.app.update({
+            uuid: opts.uuid,
+            name: opts.name,
+            folderUuid: opts.folderUuid === "null" ? null : opts.folderUuid,
+        }));
+        outputJson(result);
+    });
+    app
+        .command("remove <uuid>")
+        .description("Remove an app (also removes its deployments)")
+        .action(async (uuid) => {
+        const api = getApi();
+        await handleApiCall(() => api.hosting.app.remove(uuid));
+        outputJson({ ok: true });
+    });
+    app
+        .command("env <appUuid>")
+        .description("Print the .env.local lines a local copy of the app needs (Cargo OAuth + workspace + app UUID + API URL).")
+        .option("--api-url <url>", "Override the API URL written to the .env (default: https://api.getcargo.io)")
+        .action(async (appUuid, opts) => {
+        const api = getApi();
+        const { app: resolvedApp } = await handleApiCall(() => api.hosting.app.get(appUuid));
+        const lines = [
+            "# Generated by `cargo-ai hosting app env`. Do not commit secrets.",
+            "VITE_CARGO_OAUTH_DOMAIN=<set-by-cargo-hosting-at-deploy-time>",
+            "VITE_CARGO_OAUTH_CLIENT_ID=<set-by-cargo-hosting-at-deploy-time>",
+            "VITE_CARGO_OAUTH_AUDIENCE=<set-by-cargo-hosting-at-deploy-time>",
+            `VITE_CARGO_API_URL=${opts.apiUrl !== undefined ? opts.apiUrl : "https://api.getcargo.io"}`,
+            `VITE_CARGO_WORKSPACE_UUID=${resolvedApp.workspaceUuid}`,
+            `VITE_CARGO_APP_UUID=${resolvedApp.uuid}`,
+            "VITE_CARGO_DEPLOYMENT_UUID=<set-by-cargo-hosting-at-deploy-time>",
+            "VITE_APP_BASE_PATH=/",
+            "",
+        ];
+        process.stdout.write(lines.join("\n"));
+    });
+    app
+        .command("init <directory>")
+        .description("Scaffold a new Cargo Hosting app locally from a template (Vite + @cargo-ai/app-sdk).")
+        .option("--template <slug>", "Template slug (default: blank)", "blank")
+        .option("--name <name>", "App name written into package.json (default: directory name)")
+        .option("--list-templates", "Print available templates and exit")
+        .action(async (directory, opts) => {
+        const templatesRoot = findTemplatesRoot();
+        if (opts.listTemplates === true) {
+            const slugs = await listTemplates(templatesRoot);
+            if (slugs.length === 0) {
+                console.error(JSON.stringify({ error: "No templates found", templatesRoot }));
+                process.exit(1);
+            }
+            console.log(JSON.stringify(slugs.map((slug) => ({
+                slug,
+                description: TEMPLATE_DESCRIPTIONS[slug] !== undefined
+                    ? TEMPLATE_DESCRIPTIONS[slug]
+                    : "",
+            })), null, 2));
+            return;
+        }
+        const templateDir = path.join(templatesRoot, opts.template);
+        try {
+            const stat = await fs.stat(templateDir);
+            if (stat.isDirectory() === false) {
+                throw new Error("Template path is not a directory");
+            }
+        }
+        catch {
+            const slugs = await listTemplates(templatesRoot);
+            console.error(JSON.stringify({
+                error: `Unknown template "${opts.template}"`,
+                available: slugs,
+            }));
+            process.exit(1);
+        }
+        const targetDir = path.resolve(directory);
+        try {
+            const stat = await fs.stat(targetDir);
+            if (stat.isDirectory() === true) {
+                const entries = await fs.readdir(targetDir);
+                if (entries.length > 0) {
+                    console.error(JSON.stringify({
+                        error: `Target directory ${targetDir} is not empty.`,
+                    }));
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            // Target does not exist yet — that's fine.
+        }
+        const appName = opts.name !== undefined ? opts.name : path.basename(targetDir);
+        await copyDirectory(path.join(templatesRoot, opts.template), targetDir, [
+            { from: "__APP_NAME__", to: appName },
+            { from: "__TEMPLATE_SLUG__", to: opts.template },
+        ]);
+        console.log(JSON.stringify({
+            ok: true,
+            directory: targetDir,
+            template: opts.template,
+            name: appName,
+            nextSteps: [
+                `cd ${path.relative(process.cwd(), targetDir)}`,
+                "npm install",
+                "cargo-ai hosting app create --name '<App name>' --slug '<your-slug>'",
+                "cargo-ai hosting app env <appUuid> > .env.local",
+                "npm run dev",
+            ],
+        }, null, 2));
+    });
+}
+const TEMPLATE_DESCRIPTIONS = {
+    blank: "Minimal Vite + refine app with one route, getCargoEnv() + CargoWorkspaceBadge wired (use as a starting point).",
+    "territories-overview": "Read-only grid of revenue organization territories. Demonstrates useCargoApi() + react-query + the SDK shadcn primitives.",
+};
+const findTemplatesRoot = () => {
+    // The CLI is published as `@cargo-ai/cli`. Templates live in
+    // `@cargo-ai/app-sdk/templates`. Resolve via require so we work whether the
+    // user installed both packages globally or both came from the monorepo.
+    try {
+        const appSdkPackageJson = require.resolve("@cargo-ai/app-sdk/package.json");
+        return path.join(path.dirname(appSdkPackageJson), "templates");
+    }
+    catch {
+        const here = fileURLToPath(import.meta.url);
+        let cursor = path.dirname(here);
+        for (let i = 0; i < 6; i += 1) {
+            const candidate = path.join(cursor, "packages/app-sdk/templates");
+            try {
+                require("node:fs").accessSync(candidate);
+                return candidate;
+            }
+            catch {
+                cursor = path.dirname(cursor);
+            }
+        }
+        throw new Error("Could not locate @cargo-ai/app-sdk templates. Make sure @cargo-ai/app-sdk is installed alongside @cargo-ai/cli.");
+    }
+};

package/build/commands/hosting/deployment.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerDeploymentCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=deployment.d.ts.map

package/build/commands/hosting/deployment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../../src/commands/hosting/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA6JN"}

package/build/commands/hosting/deployment.js

@@ -0,0 +1,125 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { handleApiCall, outputJson } from "../runHandler.js";
+export function registerDeploymentCommands(parent, getApi) {
+    const deployment = parent
+        .command("deployment")
+        .description("Inspect, create, and promote deployments");
+    deployment
+        .command("list")
+        .description("List deployments for a given app or worker")
+        .option("--app-uuid <uuid>", "App UUID")
+        .option("--worker-uuid <uuid>", "Worker UUID")
+        .action(async (opts) => {
+        if (opts.appUuid === undefined && opts.workerUuid === undefined) {
+            console.error(JSON.stringify({
+                error: "Either --app-uuid or --worker-uuid must be provided.",
+            }));
+            process.exit(1);
+        }
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.deployment.list({
+            appUuid: opts.appUuid,
+            workerUuid: opts.workerUuid,
+        }));
+        outputJson(result);
+    });
+    deployment
+        .command("get <uuid>")
+        .description("Show a single deployment's status and metadata")
+        .action(async (uuid) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.deployment.get(uuid));
+        outputJson(result);
+    });
+    deployment
+        .command("get-promoted")
+        .description("Show the currently promoted deployment for an app or worker")
+        .option("--app-uuid <uuid>", "App UUID")
+        .option("--worker-uuid <uuid>", "Worker UUID")
+        .action(async (opts) => {
+        if (opts.appUuid === undefined && opts.workerUuid === undefined) {
+            console.error(JSON.stringify({
+                error: "Either --app-uuid or --worker-uuid must be provided.",
+            }));
+            process.exit(1);
+        }
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.deployment.getPromoted({
+            appUuid: opts.appUuid,
+            workerUuid: opts.workerUuid,
+        }));
+        outputJson(result);
+    });
+    deployment
+        .command("create")
+        .description("Create a new deployment by uploading a local source directory. For apps the backend runs `npm ci && vite build` in a sandbox; for workers it bundles the entrypoint.")
+        .option("--app-uuid <uuid>", "App UUID (mutually exclusive with --worker-uuid)")
+        .option("--worker-uuid <uuid>", "Worker UUID (mutually exclusive with --app-uuid)")
+        .requiredOption("--source <dir>", "Path to the source directory (typically the package root, not dist/)")
+        .option("--ignore <list>", "Comma-separated names to ignore (default: node_modules,dist,build,.git,.next)", "node_modules,dist,build,.git,.next")
+        .action(async (opts) => {
+        if ((opts.appUuid === undefined && opts.workerUuid === undefined) ||
+            (opts.appUuid !== undefined && opts.workerUuid !== undefined)) {
+            console.error(JSON.stringify({
+                error: "Exactly one of --app-uuid or --worker-uuid must be provided.",
+            }));
+            process.exit(1);
+        }
+        const api = getApi();
+        const sourceDir = path.resolve(opts.source);
+        const ignore = new Set(opts.ignore.split(",").map((entry) => entry.trim()));
+        const files = await collectFiles(sourceDir, { ignore });
+        if (files.length === 0) {
+            console.error(JSON.stringify({
+                error: `No files to deploy under ${sourceDir}`,
+            }));
+            process.exit(1);
+        }
+        const payload = opts.appUuid !== undefined
+            ? { kind: "app", appUuid: opts.appUuid, files }
+            : {
+                kind: "worker",
+                workerUuid: opts.workerUuid,
+                files,
+            };
+        const result = await handleApiCall(() => api.hosting.deployment.create(payload));
+        outputJson({
+            ...result,
+            stats: { fileCount: files.length },
+        });
+    });
+    deployment
+        .command("promote")
+        .description("Promote a deployment to the live URL")
+        .requiredOption("--uuid <uuid>", "Deployment UUID to promote")
+        .action(async (opts) => {
+        const api = getApi();
+        const result = await handleApiCall(() => api.hosting.deployment.promote({
+            uuid: opts.uuid,
+        }));
+        outputJson(result);
+    });
+}
+const collectFiles = async (rootDir, options) => {
+    const results = [];
+    const walk = async (dir, relative) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (options.ignore.has(entry.name)) {
+                continue;
+            }
+            const absolute = path.join(dir, entry.name);
+            const rel = relative.length === 0 ? entry.name : `${relative}/${entry.name}`;
+            if (entry.isDirectory() === true) {
+                await walk(absolute, rel);
+            }
+            else if (entry.isFile() === true) {
+                const content = await fs.readFile(absolute, "utf-8");
+                results.push({ path: rel, content });
+            }
+        }
+    };
+    await walk(rootDir, "");
+    return results;
+};