@moxt-ai/cli 0.2.0 → 0.3.1

package/dist/index.js

@@ -7,6 +7,118 @@ import updateNotifier from "update-notifier";
 // src/commands/file.ts
 import * as fs from "fs";
 
+// src/utils/file-selector.ts
+var SpaceOptionsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SpaceOptionsError";
+  }
+};
+function resolveSpaceSelector(options) {
+  const { space, teamSpaceId, teammateId } = options;
+  const personalIsSet = options.personal === true;
+  const spaceIsSet = space != null && space !== "";
+  const teamSpaceIdIsSet = teamSpaceId != null && teamSpaceId !== "";
+  const teammateIdIsSet = teammateId != null && teammateId !== "";
+  const selectorCount = (spaceIsSet ? 1 : 0) + (personalIsSet ? 1 : 0) + (teamSpaceIdIsSet ? 1 : 0) + (teammateIdIsSet ? 1 : 0);
+  if (selectorCount > 1) {
+    throw new SpaceOptionsError(
+      "Error: -s, --personal, --team-space-id, and --teammate-id are mutually exclusive."
+    );
+  }
+  if (teamSpaceId != null && teamSpaceId !== "") {
+    return { teamSpaceId };
+  }
+  if (teammateId != null && teammateId !== "") {
+    const parsed = Number.parseInt(teammateId, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== teammateId) {
+      throw new SpaceOptionsError(
+        `Error: --teammate-id must be a positive integer, got "${teammateId}".`
+      );
+    }
+    return { agentId: parsed };
+  }
+  if (personalIsSet) {
+    return { space: "personal" };
+  }
+  if (space != null && space !== "") {
+    return { space };
+  }
+  return {};
+}
+function buildFileQueryString(path2, spaceParams) {
+  const params = new URLSearchParams();
+  if (path2 != null && path2 !== "") {
+    params.set("path", path2);
+  }
+  if (spaceParams.space) {
+    params.set("space", spaceParams.space);
+  }
+  if (spaceParams.teamSpaceId) {
+    params.set("teamSpaceId", spaceParams.teamSpaceId);
+  }
+  if (spaceParams.agentId != null) {
+    params.set("agentId", String(spaceParams.agentId));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+function isBinaryContent(buffer2) {
+  const sampleSize = Math.min(buffer2.length, 8192);
+  for (let i = 0; i < sampleSize; i++) {
+    const byte = buffer2[i];
+    if (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) {
+      return true;
+    }
+  }
+  return false;
+}
+function resolveReadMode(options) {
+  if (options.url && options.workspace) {
+    throw new SpaceOptionsError("Error: --url cannot be used with --workspace");
+  }
+  if (options.url && options.path) {
+    throw new SpaceOptionsError("Error: --url cannot be used with --path");
+  }
+  if (!options.url && !options.workspace) {
+    throw new SpaceOptionsError("Error: Either --url or --workspace is required");
+  }
+  if (!options.url && !options.path) {
+    throw new SpaceOptionsError("Error: --path is required when not using --url");
+  }
+  if (options.url) {
+    return { kind: "by-url", url: options.url };
+  }
+  if (!options.workspace) {
+    throw new SpaceOptionsError("Error: Either --url or --workspace is required");
+  }
+  if (!options.path) {
+    throw new SpaceOptionsError("Error: --path is required when not using --url");
+  }
+  return { kind: "by-path", workspace: options.workspace, path: options.path };
+}
+function resolveWriteMode(options) {
+  if (options.url && options.workspace) {
+    throw new SpaceOptionsError("Error: --url cannot be used with --workspace");
+  }
+  if (options.url && options.path) {
+    throw new SpaceOptionsError("Error: --url cannot be used with --path");
+  }
+  if (options.url && options.recursive) {
+    throw new SpaceOptionsError("Error: --recursive cannot be used with --url (the file must already exist)");
+  }
+  if (!options.url && !options.workspace) {
+    throw new SpaceOptionsError("Error: Either --url or --workspace is required");
+  }
+  if (!options.url && !options.path) {
+    throw new SpaceOptionsError("Error: --path is required when not using --url");
+  }
+  if (options.url) {
+    return { kind: "by-url", url: options.url };
+  }
+  return { kind: "by-path", workspace: options.workspace, path: options.path };
+}
+
 // src/utils/http.ts
 import { arch, platform } from "os";
 
@@ -29,14 +141,17 @@ function getApiKey() {
   }
   return apiKey;
 }
+function getApiKeyOrUndefined() {
+  return process.env.MOXT_API_KEY;
+}
 
 // src/utils/http.ts
 function getUserAgent() {
-  return `moxt-cli/${"0.2.0"} (${platform()}/${arch()}) node/${process.versions.node}`;
+  return `moxt-cli/${"0.3.1"} (${platform()}/${arch()}) node/${process.versions.node}`;
 }
-async function request(method, path, body) {
+async function fetchApi(method, path2, body) {
   const apiKey = getApiKey();
-  const url = `${getApiBaseUrl()}${path}`;
+  const url = `${getApiBaseUrl()}${path2}`;
   const response = await fetch(url, {
     method,
     headers: {
@@ -46,35 +161,43 @@ async function request(method, path, body) {
     },
     body: body ? JSON.stringify(body) : void 0
   });
-  let data;
-  const contentType = response.headers.get("content-type");
-  if (contentType?.includes("application/json")) {
-    data = await response.json();
-  } else {
-    data = await response.text();
-  }
   if (response.status === 401) {
     console.error("Authentication failed. Check your MOXT_API_KEY.");
     console.error("Get a new key at: https://moxt.ai");
     process.exit(1);
   }
+  return response;
+}
+async function request(method, path2, body) {
+  const response = await fetchApi(method, path2, body);
+  const contentType = response.headers.get("content-type");
+  const data = contentType?.includes("application/json") ? await response.json() : await response.text();
   return {
     ok: response.ok,
     status: response.status,
     data
   };
 }
-async function httpGet(path) {
-  return request("GET", path);
+async function httpGet(path2) {
+  return request("GET", path2);
 }
-async function httpPut(path, body) {
-  return request("PUT", path, body);
+async function httpPut(path2, body) {
+  return request("PUT", path2, body);
 }
-async function httpPost(path, body) {
-  return request("POST", path, body);
+async function httpPost(path2, body) {
+  return request("POST", path2, body);
 }
-async function httpDelete(path, body) {
-  return request("DELETE", path, body);
+async function httpDelete(path2, body) {
+  return request("DELETE", path2, body);
+}
+async function httpRaw(method, path2, body) {
+  const response = await fetchApi(method, path2, body);
+  return {
+    ok: response.ok,
+    status: response.status,
+    text: await response.text(),
+    contentType: response.headers.get("content-type")
+  };
 }
 
 // src/utils/output.ts
@@ -117,59 +240,16 @@ function stopSpinner(success, message) {
 }
 
 // src/commands/file.ts
-function isBinaryContent(buffer) {
-  const sampleSize = Math.min(buffer.length, 8192);
-  for (let i = 0; i < sampleSize; i++) {
-    const byte = buffer[i];
-    if (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) {
-      return true;
-    }
-  }
-  return false;
-}
-function validateSpaceOptions(options) {
-  const mutuallyExclusive = [options.space, options.personal, options.teamSpaceId, options.teammateId].filter(
-    Boolean
-  ).length;
-  if (mutuallyExclusive > 1) {
-    printError("Error: -s, --personal, --team-space-id, and --teammate-id are mutually exclusive.");
-    process.exit(1);
-  }
-  if (options.teamSpaceId) {
-    return { teamSpaceId: options.teamSpaceId };
-  }
-  if (options.teammateId) {
-    const parsed = Number.parseInt(options.teammateId, 10);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-      printError(`Error: --teammate-id must be a positive integer, got "${options.teammateId}".`);
+function runOrExit(fn) {
+  try {
+    return fn();
+  } catch (err) {
+    if (err instanceof SpaceOptionsError) {
+      printError(err.message);
       process.exit(1);
     }
-    return { agentId: parsed };
+    throw err;
   }
-  if (options.personal) {
-    return { space: "personal" };
-  }
-  if (options.space) {
-    return { space: options.space };
-  }
-  return {};
-}
-function buildFileQueryString(path, spaceParams) {
-  const params = new URLSearchParams();
-  if (path) {
-    params.set("path", path);
-  }
-  if (spaceParams.space) {
-    params.set("space", spaceParams.space);
-  }
-  if (spaceParams.teamSpaceId) {
-    params.set("teamSpaceId", spaceParams.teamSpaceId);
-  }
-  if (spaceParams.agentId != null) {
-    params.set("agentId", String(spaceParams.agentId));
-  }
-  const qs = params.toString();
-  return qs ? `?${qs}` : "";
 }
 function addSpaceOptions(cmd) {
   return cmd.requiredOption("-w, --workspace <workspaceId>", "Workspace ID").option("-s, --space <name>", "Space name (personal or teamspace name)").option("--personal", "Use personal space (default)").option("--team-space-id <teamSpaceId>", "Team space ID").option("--teammate-id <teammateId>", "Teammate ID (teammate space)");
@@ -179,7 +259,7 @@ function registerFileCommand(program2) {
   addSpaceOptions(
     file.command("get-url").description("Resolve the shareable browser URL for a file").requiredOption("-p, --path <path>", "File path")
   ).action(async (options) => {
-    const spaceParams = validateSpaceOptions(options);
+    const spaceParams = runOrExit(() => resolveSpaceSelector(options));
     const qs = buildFileQueryString(options.path, spaceParams);
     startSpinner("Resolving URL...");
     const response = await httpGet(
@@ -202,7 +282,7 @@ function registerFileCommand(program2) {
   addSpaceOptions(
     file.command("list").description("List directory contents").option("-p, --path <path>", "Directory path", "/")
   ).action(async (options) => {
-    const spaceParams = validateSpaceOptions(options);
+    const spaceParams = runOrExit(() => resolveSpaceSelector(options));
     const qs = buildFileQueryString(options.path, spaceParams);
     startSpinner("Listing files...");
     const response = await httpGet(
@@ -217,12 +297,12 @@ function registerFileCommand(program2) {
       }
       process.exit(1);
     }
-    const { path, entries } = response.data;
+    const { path: path2, entries } = response.data;
     if (!entries || entries.length === 0) {
-      stopSpinner(true, `${path}: empty directory`);
+      stopSpinner(true, `${path2}: empty directory`);
       return;
     }
-    stopSpinner(true, path);
+    stopSpinner(true, path2);
     for (const entry of entries) {
       if (entry.type === "directory") {
         print(`${colors.blue}${entry.name}/${colors.reset}`);
@@ -232,36 +312,21 @@ function registerFileCommand(program2) {
     }
   });
   file.command("read").description("Read file content").option("-w, --workspace <workspaceId>", "Workspace ID").option("-s, --space <name>", "Space name (personal or teamspace name)").option("--personal", "Use personal space (default)").option("--team-space-id <teamSpaceId>", "Team space ID").option("--teammate-id <teammateId>", "Teammate ID (teammate space)").option("-p, --path <path>", "File path").option("-u, --url <url>", "Moxt file URL (e.g., https://moxt.ai/w/{workspaceId}/{fileId})").action(async (options) => {
-    if (options.url && options.workspace) {
-      printError("Error: --url cannot be used with --workspace");
-      process.exit(1);
-    }
-    if (options.url && options.path) {
-      printError("Error: --url cannot be used with --path");
-      process.exit(1);
-    }
-    if (!options.url && !options.workspace) {
-      printError("Error: Either --url or --workspace is required");
-      process.exit(1);
-    }
-    if (!options.url && !options.path) {
-      printError("Error: --path is required when not using --url");
-      process.exit(1);
-    }
+    const mode = runOrExit(() => resolveReadMode(options));
     startSpinner("Reading file...");
     let response;
     let displayPath;
-    if (options.url) {
-      displayPath = options.url;
+    if (mode.kind === "by-url") {
+      displayPath = mode.url;
       response = await httpGet(
-        `/files/read-by-url?url=${encodeURIComponent(options.url)}`
+        `/files/read-by-url?url=${encodeURIComponent(mode.url)}`
       );
     } else {
-      displayPath = options.path;
-      const spaceParams = validateSpaceOptions(options);
-      const qs = buildFileQueryString(options.path, spaceParams);
+      displayPath = mode.path;
+      const spaceParams = runOrExit(() => resolveSpaceSelector(options));
+      const qs = buildFileQueryString(mode.path, spaceParams);
       response = await httpGet(
-        `/workspaces/${options.workspace}/files/read${qs}`
+        `/workspaces/${mode.workspace}/files/read${qs}`
       );
     }
     if (!response.ok) {
@@ -282,11 +347,9 @@ function registerFileCommand(program2) {
     stopSpinner(true, "Done");
     print(content ?? "");
   });
-  addSpaceOptions(
-    file.command("put").description("Upload a file").requiredOption("-p, --path <path>", "Remote file path").requiredOption("-l, --local-path <localPath>", "Local file path").option("-r, --recursive", "Create parent directories if needed")
-  ).action(
+  file.command("put").description("Upload a file").option("-w, --workspace <workspaceId>", "Workspace ID").option("-s, --space <name>", "Space name (personal or teamspace name)").option("--personal", "Use personal space (default)").option("--team-space-id <teamSpaceId>", "Team space ID").option("--teammate-id <teammateId>", "Teammate ID (teammate space)").option("-p, --path <path>", "Remote file path").option("-u, --url <url>", "Moxt file URL (e.g., https://moxt.ai/w/{workspaceId}/{fileId})").requiredOption("-l, --local-path <localPath>", "Local file path").option("-r, --recursive", "Create parent directories if needed").action(
     async (options) => {
-      const spaceParams = validateSpaceOptions(options);
+      const mode = runOrExit(() => resolveWriteMode(options));
       if (!fs.existsSync(options.localPath)) {
         print(`${colors.red}\u2620 Local file not found: ${options.localPath}${colors.reset}`);
         process.exit(1);
@@ -301,26 +364,42 @@ function registerFileCommand(program2) {
         print(`${colors.red}\u2620 File too large (max 10MB): ${options.localPath}${colors.reset}`);
         process.exit(1);
       }
-      const buffer = fs.readFileSync(options.localPath);
-      if (isBinaryContent(buffer)) {
+      const buffer2 = fs.readFileSync(options.localPath);
+      if (isBinaryContent(buffer2)) {
         print(`${colors.red}\u2620 Binary files are not allowed. Only text files can be uploaded.${colors.reset}`);
         process.exit(1);
       }
-      const content = buffer.toString("utf8");
+      const content = buffer2.toString("utf8");
       startSpinner("Uploading...");
-      const response = await httpPut(
-        `/workspaces/${options.workspace}/files/write`,
-        {
-          path: options.path,
-          content,
-          recursive: options.recursive ?? false,
-          ...spaceParams
-        }
-      );
+      let response;
+      let displayPath;
+      if (mode.kind === "by-url") {
+        displayPath = mode.url;
+        response = await httpPut("/files/write-by-url", {
+          url: mode.url,
+          content
+        });
+      } else {
+        displayPath = mode.path;
+        const spaceParams = runOrExit(() => resolveSpaceSelector(options));
+        response = await httpPut(
+          `/workspaces/${mode.workspace}/files/write`,
+          {
+            path: mode.path,
+            content,
+            recursive: options.recursive ?? false,
+            ...spaceParams
+          }
+        );
+      }
       if (!response.ok) {
         stopSpinner(false, "Failed");
         if (response.status === 404) {
-          print(`${colors.red}\u2620 Parent directory does not exist${colors.reset}`);
+          if (mode.kind === "by-url") {
+            print(`${colors.red}\u2620 ${displayPath} does not exist${colors.reset}`);
+          } else {
+            print(`${colors.red}\u2620 Parent directory does not exist${colors.reset}`);
+          }
         } else if (response.status === 400) {
           printError(`Error: ${JSON.stringify(response.data)}`);
         } else {
@@ -336,7 +415,7 @@ function registerFileCommand(program2) {
     file.command("mkdir").description("Create a directory").requiredOption("-p, --path <path>", "Directory path").option("-r, --recursive", "Create parent directories if needed")
   ).action(
     async (options) => {
-      const spaceParams = validateSpaceOptions(options);
+      const spaceParams = runOrExit(() => resolveSpaceSelector(options));
       startSpinner("Creating directory...");
       const response = await httpPost(
         `/workspaces/${options.workspace}/files/mkdir`,
@@ -365,7 +444,7 @@ function registerFileCommand(program2) {
     file.command("del").description("Delete a file or empty directory").requiredOption("-p, --path <path>", "File or directory path")
   ).action(
     async (options) => {
-      const spaceParams = validateSpaceOptions(options);
+      const spaceParams = runOrExit(() => resolveSpaceSelector(options));
       startSpinner("Deleting...");
       const response = await httpDelete(
         `/workspaces/${options.workspace}/files/delete`,
@@ -390,6 +469,231 @@ function registerFileCommand(program2) {
   );
 }
 
+// src/utils/miniapp-db.ts
+var MiniappDbOptionsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MiniappDbOptionsError";
+  }
+};
+var NON_FILTER_QUERY_PARAMS = /* @__PURE__ */ new Set([
+  "select",
+  "order",
+  "limit",
+  "offset",
+  "range",
+  "range-unit"
+]);
+var ALLOWED_MINIAPP_DB_EMAIL_DOMAINS = ["@paraflow.com", "@moxt.ai", "@kanyun.com"];
+function normalizePostgrestPath(path2) {
+  const trimmed = path2.trim();
+  if (!trimmed) {
+    throw new MiniappDbOptionsError("Error: PostgREST path is required.");
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function buildMiniappDbDataPath(workspaceId, appId, postgrestPath) {
+  return `/workspaces/${encodeURIComponent(workspaceId)}/miniapps/${encodeURIComponent(appId)}/db/data${normalizePostgrestPath(postgrestPath)}`;
+}
+function buildMiniappDbSchemaPath(workspaceId, appId) {
+  return `/workspaces/${encodeURIComponent(workspaceId)}/miniapps/${encodeURIComponent(appId)}/db/schema`;
+}
+function parseJsonBody(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new MiniappDbOptionsError(`Error: --body must be valid JSON. ${detail}`);
+  }
+  if (parsed === null || typeof parsed !== "object" && !Array.isArray(parsed)) {
+    throw new MiniappDbOptionsError("Error: --body must be a JSON object or array.");
+  }
+  return parsed;
+}
+function hasPostgrestFilter(postgrestPath) {
+  const normalizedPath = normalizePostgrestPath(postgrestPath);
+  const parsed = new URL(normalizedPath, "https://postgrest.local");
+  for (const [name] of parsed.searchParams.entries()) {
+    if (!NON_FILTER_QUERY_PARAMS.has(name.toLowerCase())) {
+      return true;
+    }
+  }
+  return false;
+}
+function assertPostgrestFilter(postgrestPath, method) {
+  if (!hasPostgrestFilter(postgrestPath)) {
+    throw new MiniappDbOptionsError(
+      `Error: ${method.toLowerCase()} requires at least one PostgREST filter query parameter.`
+    );
+  }
+}
+function formatRawResponse(text, pretty) {
+  if (!pretty || !text) {
+    return text;
+  }
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+function isAllowedMiniappDbUserEmail(email) {
+  const normalized = email.trim().toLowerCase();
+  return ALLOWED_MINIAPP_DB_EMAIL_DOMAINS.some((domain) => normalized.endsWith(domain));
+}
+
+// src/commands/miniapp.ts
+function runOrExit2(fn) {
+  try {
+    return fn();
+  } catch (err) {
+    if (err instanceof MiniappDbOptionsError) {
+      printError(err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+function addMiniappDbTargetOptions(command) {
+  return command.requiredOption("-w, --workspace <workspaceId>", "Workspace ID").requiredOption("--app-id <appId>", "Miniapp app ID");
+}
+function handleRawResponse(response, pretty) {
+  if (!response.ok) {
+    printError(`Error [${response.status}]: ${response.text}`);
+    process.exit(1);
+  }
+  print(formatRawResponse(response.text, pretty));
+}
+async function ensureAllowedMiniappDbUser() {
+  const response = await httpGet("/users/whoami");
+  if (!response.ok) {
+    printError(`Error [${response.status}]: ${JSON.stringify(response.data)}`);
+    process.exit(1);
+  }
+  if (!isAllowedMiniappDbUserEmail(response.data.email)) {
+    printError("Error: miniapp db commands are only available to @paraflow.com, @moxt.ai, or @kanyun.com users.");
+    process.exit(1);
+  }
+}
+async function requestDataApi(method, postgrestPath, options, body) {
+  await ensureAllowedMiniappDbUser();
+  const path2 = buildMiniappDbDataPath(options.workspace, options.appId, postgrestPath);
+  const response = await httpRaw(method, path2, body);
+  handleRawResponse(response, options.pretty);
+}
+function registerMiniappCommand(program2) {
+  const miniapp = program2.command("miniapp", { hidden: true }).description("Miniapp operations");
+  const db = miniapp.command("db").description("Miniapp database operations");
+  addMiniappDbTargetOptions(
+    db.command("schema").description("Print the miniapp database schema SQL")
+  ).action(async (options) => {
+    await ensureAllowedMiniappDbUser();
+    const response = await httpGet(buildMiniappDbSchemaPath(options.workspace, options.appId));
+    if (!response.ok) {
+      printError(`Error [${response.status}]: ${JSON.stringify(response.data)}`);
+      process.exit(1);
+    }
+    print(response.data.sql);
+  });
+  addMiniappDbTargetOptions(
+    db.command("get").description("Read miniapp data through PostgREST").argument("<path>", "PostgREST path, for example /todos?select=*").option("--pretty", "Pretty-print JSON responses")
+  ).action(async (postgrestPath, options) => {
+    await requestDataApi("GET", postgrestPath, options);
+  });
+  addMiniappDbTargetOptions(
+    db.command("post").description("Create miniapp data through PostgREST").argument("<path>", "PostgREST path, for example /todos").requiredOption("--body <json>", "JSON object or array request body").option("--pretty", "Pretty-print JSON responses")
+  ).action(async (postgrestPath, options) => {
+    const body = runOrExit2(() => parseJsonBody(options.body ?? ""));
+    await requestDataApi("POST", postgrestPath, options, body);
+  });
+  addMiniappDbTargetOptions(
+    db.command("patch").description("Update miniapp data through PostgREST").argument("<path>", "PostgREST path with a filter, for example /todos?id=eq.1").requiredOption("--body <json>", "JSON object or array request body").option("--pretty", "Pretty-print JSON responses")
+  ).action(async (postgrestPath, options) => {
+    runOrExit2(() => assertPostgrestFilter(postgrestPath, "PATCH"));
+    const body = runOrExit2(() => parseJsonBody(options.body ?? ""));
+    await requestDataApi("PATCH", postgrestPath, options, body);
+  });
+  addMiniappDbTargetOptions(
+    db.command("delete").description("Delete miniapp data through PostgREST").argument("<path>", "PostgREST path with a filter, for example /todos?id=eq.1").option("--yes", "Confirm the delete operation").option("--pretty", "Pretty-print JSON responses")
+  ).action(async (postgrestPath, options) => {
+    if (options.yes !== true) {
+      printError("Error: delete requires --yes.");
+      process.exit(1);
+    }
+    runOrExit2(() => assertPostgrestFilter(postgrestPath, "DELETE"));
+    await requestDataApi("DELETE", postgrestPath, options);
+  });
+}
+
+// src/telemetry/config.ts
+import * as fs2 from "fs";
+import * as os from "os";
+import * as path from "path";
+function getConfigPath() {
+  return path.join(os.homedir(), ".moxt", "config.json");
+}
+function readTelemetryConfig() {
+  try {
+    const raw = fs2.readFileSync(getConfigPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.telemetry ?? {};
+  } catch {
+    return {};
+  }
+}
+function writeTelemetryConfig(update) {
+  const configPath = getConfigPath();
+  let existing = {};
+  try {
+    existing = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+  } catch {
+    existing = {};
+  }
+  const currentTelemetry = existing.telemetry ?? {};
+  const next = { ...existing, telemetry: { ...currentTelemetry, ...update } };
+  fs2.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs2.writeFileSync(configPath, JSON.stringify(next, null, 2));
+}
+
+// src/telemetry/opt-out.ts
+function isCiEnvironment() {
+  return process.env.CI === "true" || process.env.CI === "1";
+}
+function isTelemetryDisabled() {
+  if (process.env.MOXT_TELEMETRY_DISABLED === "1" || process.env.MOXT_TELEMETRY_DISABLED === "true") {
+    return true;
+  }
+  if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true") {
+    return true;
+  }
+  return readTelemetryConfig().disabled === true;
+}
+
+// src/commands/telemetry.ts
+function registerTelemetryCommand(program2) {
+  const telemetry = program2.command("telemetry").description("Manage Moxt CLI telemetry");
+  telemetry.command("status").description("Show telemetry status").action(() => {
+    const cfg = readTelemetryConfig();
+    const envOverride = process.env.MOXT_TELEMETRY_DISABLED === "1" || process.env.MOXT_TELEMETRY_DISABLED === "true" || process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true";
+    const state = isTelemetryDisabled() ? "disabled" : "enabled";
+    print(`telemetry: ${state}`);
+    if (envOverride) {
+      print("(disabled via environment variable)");
+    } else if (cfg.disabled) {
+      print("(disabled via config file)");
+    }
+  });
+  telemetry.command("enable").description("Enable telemetry").action(() => {
+    writeTelemetryConfig({ disabled: false });
+    print("telemetry: enabled");
+  });
+  telemetry.command("disable").description("Disable telemetry").action(() => {
+    writeTelemetryConfig({ disabled: true });
+    print("telemetry: disabled");
+  });
+}
+
 // src/commands/whoami.ts
 function registerWhoamiCommand(program2) {
   program2.command("whoami").description("Show current user information").action(async () => {
@@ -519,19 +823,218 @@ function registerWorkspaceCommand(program2) {
   });
 }
 
+// src/telemetry/client.ts
+import { arch as arch2, platform as platform2 } from "os";
+var buffer = [];
+var FLUSH_TIMEOUT_MS = 3e3;
+var MAX_BATCH_SIZE = 100;
+function commonLabels() {
+  return {
+    cli_version: "0.3.1",
+    node_version: process.versions.node,
+    os: platform2(),
+    arch: arch2(),
+    is_ci: isCiEnvironment() ? "true" : "false"
+  };
+}
+function record(metric) {
+  if (isTelemetryDisabled()) {
+    debugLog(`record: disabled, dropping ${metric.metric_id}`);
+    return;
+  }
+  if (!getApiKeyOrUndefined()) {
+    debugLog(`record: no API key, dropping ${metric.metric_id}`);
+    return;
+  }
+  buffer.push({
+    ...metric,
+    extra_label_name_2_value: {
+      ...commonLabels(),
+      ...metric.extra_label_name_2_value ?? {}
+    }
+  });
+  debugLog(`record: buffered ${metric.metric_id} (buffer=${buffer.length})`);
+}
+function isDebug() {
+  return process.env.MOXT_TELEMETRY_DEBUG === "1" || process.env.MOXT_TELEMETRY_DEBUG === "true";
+}
+function debugLog(msg, detail) {
+  if (!isDebug()) return;
+  process.stderr.write(`[telemetry] ${msg}${detail !== void 0 ? ` ${JSON.stringify(detail)}` : ""}
+`);
+}
+async function flush() {
+  if (buffer.length === 0) {
+    debugLog("flush: buffer empty, skipping");
+    return;
+  }
+  const apiKey = getApiKeyOrUndefined();
+  if (!apiKey) {
+    debugLog("flush: no API key, dropping buffer");
+    buffer.length = 0;
+    return;
+  }
+  const batch = buffer.splice(0, MAX_BATCH_SIZE);
+  const payload = {
+    release_id: "0.3.1",
+    client_type: "cli",
+    metric_data_list: batch.map((m) => ({
+      profile: "cli",
+      metric_id: m.metric_id,
+      metric_type: m.metric_type,
+      value: m.value,
+      extra_label_name_2_value: m.extra_label_name_2_value
+    }))
+  };
+  const url = `${getApiBaseUrl()}/cli-metrics`;
+  debugLog(`flush: POST ${url} with ${batch.length} metrics`, payload);
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, FLUSH_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      debugLog(`flush: response status=${res.status}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch (err) {
+    debugLog("flush: failed", err instanceof Error ? err.message : String(err));
+  }
+}
+
+// src/telemetry/notice.ts
+var NOTICE = [
+  "",
+  "Attention: Moxt CLI now collects anonymous telemetry regarding usage.",
+  "This information is used to shape Moxt CLI's roadmap and prioritize features.",
+  "",
+  "You may opt out by setting MOXT_TELEMETRY_DISABLED=1 in your env",
+  "or by running `moxt telemetry disable`.",
+  "Details: https://www.npmjs.com/package/@moxt-ai/cli#telemetry",
+  ""
+];
+function maybeShowTelemetryNotice() {
+  if (isTelemetryDisabled()) return;
+  if (isCiEnvironment()) return;
+  if (readTelemetryConfig().noticeShown) return;
+  for (const line of NOTICE) {
+    process.stderr.write(`${line}
+`);
+  }
+  try {
+    writeTelemetryConfig({ noticeShown: true });
+  } catch {
+  }
+}
+
+// src/telemetry/instrument.ts
+var current = null;
+function commandPath(cmd) {
+  const names = [];
+  let node = cmd;
+  while (node && node.parent) {
+    names.unshift(node.name());
+    node = node.parent;
+  }
+  if (names.length === 0) return { command: "unknown" };
+  if (names.length === 1) return { command: names[0] };
+  return { command: names[0], subcommand: names.slice(1).join(" ") };
+}
+function instrumentProgram(program2) {
+  program2.hook("preAction", (_thisCommand, actionCommand) => {
+    const { command, subcommand } = commandPath(actionCommand);
+    if (command !== "telemetry") {
+      maybeShowTelemetryNotice();
+    }
+    current = { name: command, subcommand, startedAt: Date.now() };
+    record({
+      metric_id: "client.cli.command_invocation.count",
+      metric_type: "counter",
+      value: 1,
+      extra_label_name_2_value: {
+        command,
+        ...subcommand ? { subcommand } : {},
+        status: "started"
+      }
+    });
+  });
+  program2.hook("postAction", async () => {
+    await reportOutcome("success");
+  });
+}
+async function reportOutcome(status, errorCode) {
+  if (!current) return;
+  const { name, subcommand, startedAt } = current;
+  const durationSeconds = (Date.now() - startedAt) / 1e3;
+  record({
+    metric_id: "client.cli.command_duration_seconds",
+    metric_type: "histogram",
+    value: durationSeconds,
+    extra_label_name_2_value: {
+      command: name,
+      ...subcommand ? { subcommand } : {},
+      status
+    }
+  });
+  if (status === "error") {
+    record({
+      metric_id: "client.cli.command_error.count",
+      metric_type: "counter",
+      value: 1,
+      extra_label_name_2_value: {
+        command: name,
+        ...subcommand ? { subcommand } : {},
+        ...errorCode ? { error_code: errorCode } : {}
+      }
+    });
+  }
+  current = null;
+  await flush();
+}
+function installExitHandler() {
+  const handleError = (errorCode) => {
+    void reportOutcome("error", errorCode);
+  };
+  process.on("uncaughtException", () => {
+    handleError("uncaught_exception");
+    process.exit(1);
+  });
+  process.on("unhandledRejection", () => {
+    handleError("unhandled_rejection");
+    process.exit(1);
+  });
+}
+
 // src/index.ts
 updateNotifier({
-  pkg: { name: "@moxt-ai/cli", version: "0.2.0" }
+  pkg: { name: "@moxt-ai/cli", version: "0.3.1" }
 }).notify();
 var program = new Command();
-program.name("moxt").description("Moxt CLI - AI Workspace").version("0.2.0").action(() => {
+program.name("moxt").description("Moxt CLI - AI Workspace").version("0.3.1").action(() => {
   program.help();
 });
+instrumentProgram(program);
+installExitHandler();
 registerWhoamiCommand(program);
 registerWorkspaceCommand(program);
 registerFileCommand(program);
-program.parseAsync(process.argv).catch((err) => {
+registerMiniappCommand(program);
+registerTelemetryCommand(program);
+program.parseAsync(process.argv).then(async () => {
+  await flush();
+}).catch(async (err) => {
   console.error("CLI Error:", err);
+  await flush();
   process.exit(1);
 });
 //# sourceMappingURL=index.js.map