@senso-ai/cli 0.5.0 → 0.6.1

package/dist/cli.js

@@ -578,6 +578,38 @@ function registerApiKeyCommands(program2) {
       process.exit(1);
     }
   });
+  keys.command("kb-permissions-get <keyId>").description("Get the knowledge base node permission grants configured for an API key.").action(async (keyId) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/api-keys/${keyId}/kb-permissions`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  keys.command("kb-permissions-set <keyId>").description("Set KB node permission grants for an API key. Replaces any existing grants. Each grant requires a node_id (UUID) and role (viewer|editor|owner|admin).").requiredOption("--data <json>", 'JSON: { "grants": [{ "node_id": "<uuid>", "role": "viewer" }] }').action(async (keyId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PUT", path: `/org/api-keys/${keyId}/kb-permissions`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`KB permissions updated for key ${keyId}.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  keys.command("kb-permissions-delete <keyId>").description("Remove all KB node permission grants from an API key, restoring full org-level access.").action(async (keyId) => {
+    const opts = program2.opts();
+    try {
+      await apiRequest({ method: "DELETE", path: `/org/api-keys/${keyId}/kb-permissions`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`KB permissions removed from key ${keyId}.`);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/search.ts
@@ -716,6 +748,25 @@ function registerSearchCommands(program2) {
       process.exit(1);
     }
   });
+  search.command("full <query>").description("Alias for the default search \u2014 returns AI answer plus matching chunks. Equivalent to 'senso search <query>'.").option("--max-results <n>", "Maximum results", "5").option("--content-ids <ids...>", "Restrict search to specific content item IDs (space-separated UUIDs)").option("--require-scoped-ids", "Only return results from the specified --content-ids").action(async (query, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = { query, max_results: parseInt(cmdOpts.maxResults) };
+      if (cmdOpts.contentIds) body.content_ids = cmdOpts.contentIds;
+      if (cmdOpts.requireScopedIds) body.require_scoped_ids = true;
+      const data = await apiRequest({
+        method: "POST",
+        path: "/org/search/full",
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      outputByFormat(opts.output, data);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 function outputByFormat(format, data) {
   if (format === "json") {
@@ -786,7 +837,7 @@ function registerIngestCommands(program2) {
       const fileData = await Promise.all(files.map(getFileMetadata));
       const results = await apiRequest({
         method: "POST",
-        path: "/org/ingestion/upload",
+        path: "/org/kb/upload",
         body: { files: fileData.map((f) => f.meta) },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
@@ -796,10 +847,16 @@ function registerIngestCommands(program2) {
       for (const item of items) {
         if (item.status === "upload_pending" && item.upload_url) {
           const match = fileData.find((f) => f.meta.filename === item.filename);
-          if (match) {
+          if (!match) {
+            error(`Could not match server filename "${item.filename}" to a local file \u2014 skipping upload.`);
+            continue;
+          }
+          try {
             await uploadToS3(item.upload_url, match.buffer, match.meta.content_type);
             uploaded++;
             success(`Uploaded ${item.filename} (content_id: ${item.content_id})`);
+          } catch (uploadErr) {
+            error(`S3 upload failed for ${item.filename}: ${uploadErr instanceof Error ? uploadErr.message : String(uploadErr)}`);
           }
         } else {
           warn(`Skipped ${item.filename}: ${item.status}${item.message ? ` \u2014 ${item.message}` : ""}`);
@@ -822,7 +879,7 @@ function registerIngestCommands(program2) {
       const { meta, buffer } = await getFileMetadata(file);
       const results = await apiRequest({
         method: "PUT",
-        path: `/org/ingestion/content/${contentId}`,
+        path: `/org/kb/nodes/${contentId}/file`,
         body: { file: meta },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
@@ -850,29 +907,30 @@ function registerIngestCommands(program2) {
 import pc6 from "picocolors";
 function registerContentCommands(program2) {
   const content = program2.command("content").description("Manage content items in the knowledge base. List, inspect, delete, unpublish, and manage the verification workflow and ownership of content.");
-  content.command("list").description("List all content items in the knowledge base. Returns title, status, and ID for each item. Use --search to filter by title, --sort to order results.").option("--limit <n>", "Items per page", "10").option("--offset <n>", "Pagination offset", "0").option("--search <query>", "Filter content by title").option("--sort <order>", "Sort order: title_asc, title_desc, created_asc, created_desc").action(async (cmdOpts) => {
+  content.command("list").description("List top-level files and folders in the knowledge base. Use 'kb my-files' for the same result with richer KB node output.").option("--limit <n>", "Items per page", "10").option("--offset <n>", "Pagination offset", "0").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const data = await apiRequest({
-        path: "/org/content",
-        params: { limit: cmdOpts.limit, offset: cmdOpts.offset, search: cmdOpts.search, sort: cmdOpts.sort },
+        path: "/org/kb/my-files",
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
       const format = opts.output || "plain";
-      const rows = Array.isArray(data) ? data : [];
+      const rows = Array.isArray(data) ? data : data.nodes ?? [];
       output(format, {
         json: data,
         table: {
           rows: rows.map((r) => ({
-            id: r.id || r.content_id,
-            title: r.title,
-            status: r.status
+            id: r.node_id,
+            name: r.name,
+            type: r.type,
+            status: r.processing_status
           })),
-          columns: ["id", "title", "status"]
+          columns: ["id", "name", "type", "status"]
         },
         plain: rows.length ? rows.map(
-          (r) => `  ${pc6.bold(String(r.title || "Untitled"))} ${pc6.dim(`(${r.id || r.content_id})`)} ${r.status ? pc6.dim(`[${r.status}]`) : ""}`
+          (r) => `  ${pc6.bold(String(r.name || "Untitled"))} ${pc6.dim(`(${r.node_id})`)} ${r.type ? pc6.dim(`[${r.type}]`) : ""}`
         ) : ["  No content found."]
       });
     } catch (err) {
@@ -1032,7 +1090,7 @@ function registerGenerateCommands(program2) {
       process.exit(1);
     }
   });
-  gen.command("run").description("Trigger a content generation run. Processes all prompts (or a specific subset) through the content engine. Runs asynchronously \u2014 use 'content verification' to monitor generated drafts after the run completes.").option("--prompt-ids <ids...>", "Optional list of prompt IDs to process (omit to run all)").action(async (cmdOpts) => {
+  gen.command("run").description("Trigger a content generation run. Processes all prompts (or a specific subset) through the content engine. Runs asynchronously \u2014 use 'generate runs-list' to monitor progress.").option("--prompt-ids <ids...>", "Optional list of prompt IDs to process (omit to run all)").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = cmdOpts.promptIds ? { prompt_ids: cmdOpts.promptIds } : void 0;
@@ -1044,6 +1102,78 @@ function registerGenerateCommands(program2) {
       process.exit(1);
     }
   });
+  gen.command("job-context").description("Get the full content generation job context \u2014 all prompts with queue status (create vs update), content state, and a summary of queue counts.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/content-generation/job-context", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-list").description("List content generation runs for the org. Use --status to filter by run status, --active-only to show only in-progress runs.").option("--limit <n>", "Items per page", "20").option("--offset <n>", "Pagination offset", "0").option("--status <status>", "Filter by run status").option("--active-only", "Only return active (in-progress) runs").option("--start-date <date>", "Filter runs on or after this date (YYYY-MM-DD)").option("--end-date <date>", "Filter runs on or before this date (YYYY-MM-DD)").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: "/org/content-generation/runs",
+        params: {
+          limit: cmdOpts.limit,
+          offset: cmdOpts.offset,
+          status: cmdOpts.status,
+          active_only: cmdOpts.activeOnly ? "true" : void 0,
+          start_date: cmdOpts.startDate,
+          end_date: cmdOpts.endDate
+        },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-get <runId>").description("Get details for a specific content generation run.").action(async (runId) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/content-generation/runs/${runId}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-items <runId>").description("List individual prompt items within a content generation run and their per-item status.").option("--limit <n>", "Items per page", "100").option("--offset <n>", "Pagination offset", "0").action(async (runId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/content-generation/runs/${runId}/items`,
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-logs <runId>").description("List log entries for a content generation run.").option("--limit <n>", "Items per page", "100").option("--offset <n>", "Pagination offset", "0").action(async (runId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/content-generation/runs/${runId}/logs`,
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/engine.ts
@@ -1371,19 +1501,30 @@ function registerMemberCommands(program2) {
   });
 }
 
-// src/commands/notifications.ts
-function registerNotificationCommands(program2) {
-  const notif = program2.command("notifications").description("View and manage user notifications. Notifications are triggered by content verification, generation runs, and other system events.");
-  notif.command("list").description("List notifications for the current user. Use --unread-only to filter to unread notifications.").option("--limit <n>", "Maximum notifications to return (default: 50, max: 200)").option("--offset <n>", "Number of notifications to skip (for pagination)").option("--unread-only", "Only return unread notifications").action(async (cmdOpts) => {
+// src/commands/credits.ts
+function registerCreditsCommands(program2) {
+  const credits = program2.command("credits").description("View your organisation's credit balance. Credits are consumed by AI content generation and search operations.");
+  credits.command("balance").description("Get the current credit balance for the organisation. Returns available credits and any spend limit configured.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/credits/balance", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/questions.ts
+function registerQuestionsCommands(program2) {
+  const questions = program2.command("questions").description("Manage org-scoped geo questions. These are lightweight CRUD questions distinct from prompts (which include full run history).");
+  questions.command("list").description("List geo questions for the org.").option("--type <type>", "Filter by question type: organization | network", "organization").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const data = await apiRequest({
-        path: "/app/v1/notifications",
-        params: {
-          limit: cmdOpts.limit,
-          offset: cmdOpts.offset,
-          unread_only: cmdOpts.unreadOnly ? "true" : void 0
-        },
+        path: "/org/questions",
+        params: { question_type: cmdOpts.type },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -1393,16 +1534,354 @@ function registerNotificationCommands(program2) {
       process.exit(1);
     }
   });
-  notif.command("read <id>").description("Mark a notification as read.").action(async (id) => {
+  questions.command("create").description("Create a new geo question. Type must be one of: decision, consideration, awareness, evaluation.").requiredOption("--data <json>", 'JSON: { "question_text": "...", "type": "decision", "tag_ids": [] }').action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
-      await apiRequest({
-        method: "PATCH",
-        path: `/app/v1/notifications/${id}/read`,
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "POST", path: "/org/questions", body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success("Question created.");
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  questions.command("patch <questionId>").description("Partially update a question. Currently supports updating tag associations.").requiredOption("--data <json>", 'JSON: { "tag_ids": ["<uuid>", ...] } \u2014 pass null to clear all tags').action(async (questionId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PATCH", path: `/org/questions/${questionId}`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Question ${questionId} updated.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  questions.command("delete <questionId>").description("Delete a geo question.").action(async (questionId) => {
+    const opts = program2.opts();
+    try {
+      await apiRequest({ method: "DELETE", path: `/org/questions/${questionId}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Question ${questionId} deleted.`);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/kb.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile2, stat as stat2 } from "fs/promises";
+import { basename as basename2, resolve as resolve2 } from "path";
+var MIME_TYPES2 = {
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".csv": "text/csv",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".xml": "application/xml"
+};
+function getMimeType2(filename) {
+  const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+  return MIME_TYPES2[ext] || "application/octet-stream";
+}
+async function getFileMetadata2(filePath) {
+  const absPath = resolve2(filePath);
+  const buffer = await readFile2(absPath);
+  const stats = await stat2(absPath);
+  const hash = createHash2("md5").update(buffer).digest("hex");
+  return {
+    meta: {
+      filename: basename2(absPath),
+      file_size_bytes: stats.size,
+      content_type: getMimeType2(basename2(absPath)),
+      content_hash_md5: hash
+    },
+    buffer
+  };
+}
+async function uploadToS32(url, buffer, contentType) {
+  const res = await fetch(url, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: buffer
+  });
+  if (!res.ok) throw new Error(`S3 upload failed: ${res.status} ${res.statusText}`);
+}
+function registerKBCommands(program2) {
+  const kb = program2.command("kb").description("Manage the knowledge base. Browse nodes, upload files, create folders, create raw content, and manage the KB tree.");
+  kb.command("root").description("Get the root KB node for the org.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/kb/root", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("my-files").description("List top-level files and folders in the knowledge base.").option("--limit <n>", "Items per page", "50").option("--offset <n>", "Pagination offset", "0").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: "/org/kb/my-files",
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("find").description("Search KB nodes by name.").requiredOption("--query <q>", "Name search query").option("--limit <n>", "Items per page", "20").option("--offset <n>", "Pagination offset", "0").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: "/org/kb/find",
+        params: { q: cmdOpts.query, limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("sync-status").description("Get the vector sync status for the org's knowledge base.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/kb/sync-status", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("get <id>").description("Get a KB node by ID.").action(async (id) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/kb/nodes/${id}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("children <id>").description("List children of a KB folder node.").option("--limit <n>", "Items per page", "50").option("--offset <n>", "Pagination offset", "0").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/kb/nodes/${id}/children`,
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("ancestors <id>").description("Get the ancestor chain (breadcrumb) for a KB node.").action(async (id) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/kb/nodes/${id}/ancestors`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("get-content <id>").description("Get the content detail for a KB content node.").option("--version <version>", "Specific version to retrieve").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/kb/nodes/${id}/content`,
+        params: { version: cmdOpts.version },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("download-url <id>").description("Get a presigned S3 download URL for a KB file node.").option("--version <version>", "Specific version to download").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/kb/nodes/${id}/download-url`,
+        params: { version: cmdOpts.version },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
-      success(`Notification ${id} marked as read.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("create-folder").description("Create a new folder in the knowledge base.").requiredOption("--name <name>", "Folder name").option("--parent-id <id>", "Parent folder node ID (omit to create at root)").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = { name: cmdOpts.name };
+      if (cmdOpts.parentId) body.parent_node_id = cmdOpts.parentId;
+      const data = await apiRequest({ method: "POST", path: "/org/kb/folders", body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Folder "${cmdOpts.name}" created.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("rename <id>").description("Rename a KB node.").requiredOption("--name <name>", "New name").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ method: "PATCH", path: `/org/kb/nodes/${id}/rename`, body: { name: cmdOpts.name }, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} renamed to "${cmdOpts.name}".`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("move <id>").description("Move a KB node to a different parent folder.").requiredOption("--parent-id <parentId>", "Target parent folder node ID").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ method: "PATCH", path: `/org/kb/nodes/${id}/move`, body: { parent_node_id: cmdOpts.parentId }, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} moved.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("delete <id>").description("Delete a KB node (soft delete).").action(async (id) => {
+    const opts = program2.opts();
+    try {
+      await apiRequest({ method: "DELETE", path: `/org/kb/nodes/${id}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} deleted.`);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("create-raw").description("Create a raw (text/markdown) content item in the knowledge base.").requiredOption("--data <json>", 'JSON: { "name": "My doc", "text": "# Hello", "kb_folder_node_id": "<uuid>" }').action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "POST", path: "/org/kb/raw", body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success("Raw content node created.");
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("update-raw <id>").description("Fully replace the text content of a raw KB node (creates a new version).").requiredOption("--data <json>", 'JSON: { "text": "# Updated content" }').action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PUT", path: `/org/kb/nodes/${id}/raw`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} content replaced.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("patch-raw <id>").description("Partially update the text content of a raw KB node.").requiredOption("--data <json>", 'JSON: { "text": "Updated text", "name": "New name" }').action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PATCH", path: `/org/kb/nodes/${id}/raw`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} content patched.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("upload <files...>").description("Upload files to the knowledge base (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker.").option("--folder-id <id>", "Parent folder node ID to place files in (omit for root)").action(async (files, cmdOpts) => {
+    const opts = program2.opts();
+    if (files.length > 10) {
+      error("Maximum 10 files per upload request.");
+      process.exit(1);
+    }
+    try {
+      const fileData = await Promise.all(files.map(getFileMetadata2));
+      const body = { files: fileData.map((f) => f.meta) };
+      if (cmdOpts.folderId) body.kb_folder_node_id = cmdOpts.folderId;
+      const results = await apiRequest({
+        method: "POST",
+        path: "/org/kb/upload",
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      const items = Array.isArray(results) ? results : [];
+      let uploaded = 0;
+      for (const item of items) {
+        if (item.status === "upload_pending" && item.upload_url) {
+          const match = fileData.find((f) => f.meta.filename === item.filename);
+          if (!match) {
+            error(`Could not match server filename "${item.filename}" to a local file \u2014 skipping upload.`);
+            continue;
+          }
+          try {
+            await uploadToS32(item.upload_url, match.buffer, match.meta.content_type);
+            uploaded++;
+            success(`Uploaded ${item.filename} (content_id: ${item.content_id})`);
+          } catch (uploadErr) {
+            error(`S3 upload failed for ${item.filename}: ${uploadErr instanceof Error ? uploadErr.message : String(uploadErr)}`);
+          }
+        } else {
+          warn(`Skipped ${item.filename}: ${item.status}${item.message ? ` \u2014 ${item.message}` : ""}`);
+        }
+      }
+      if (uploaded > 0) {
+        success(`${uploaded} file(s) uploaded. Background processing will parse, chunk, and embed them.`);
+      }
+      if (opts.output === "json") console.log(JSON.stringify(results, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("update-file <id> <file>").description("Replace the file on an existing KB file node with a new version.").action(async (id, file) => {
+    const opts = program2.opts();
+    try {
+      const { meta, buffer } = await getFileMetadata2(file);
+      const results = await apiRequest({
+        method: "PUT",
+        path: `/org/kb/nodes/${id}/file`,
+        body: { file: meta },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      const items = Array.isArray(results) ? results : [];
+      for (const item of items) {
+        if (item.status === "upload_pending" && item.upload_url) {
+          await uploadToS32(item.upload_url, buffer, meta.content_type);
+          success(`Uploaded ${meta.filename} for node ${id}. Background re-processing started.`);
+        } else {
+          warn(`Skipped: ${item.status}${item.message ? ` \u2014 ${item.message}` : ""}`);
+        }
+      }
+      if (opts.output === "json") console.log(JSON.stringify(results, null, 2));
     } catch (err) {
       error(formatApiError(err));
       process.exit(1);
@@ -1410,13 +1889,13 @@ function registerNotificationCommands(program2) {
   });
 }
 
-// src/commands/credits.ts
-function registerCreditsCommands(program2) {
-  const credits = program2.command("credits").description("View your organisation's credit balance. Credits are consumed by AI content generation and search operations.");
-  credits.command("balance").description("Get the current credit balance for the organisation. Returns available credits and any spend limit configured.").action(async () => {
+// src/commands/permissions.ts
+function registerPermissionsCommands(program2) {
+  const perms = program2.command("permissions").description("View available role permissions for the organization.");
+  perms.command("list").description("List all available permission keys with their names, descriptions, and categories. Useful for building role management UIs.").action(async () => {
     const opts = program2.opts();
     try {
-      const data = await apiRequest({ path: "/org/credits/balance", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      const data = await apiRequest({ path: "/org/permissions", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
       console.log(JSON.stringify(data, null, 2));
     } catch (err) {
       error(formatApiError(err));
@@ -1482,8 +1961,10 @@ registerContentTypeCommands(program);
 registerPromptCommands(program);
 registerRunConfigCommands(program);
 registerMemberCommands(program);
-registerNotificationCommands(program);
 registerCreditsCommands(program);
+registerQuestionsCommands(program);
+registerKBCommands(program);
+registerPermissionsCommands(program);
 registerUpdateCommand(program);
 async function main() {
   const quiet = process.argv.includes("--quiet") || process.argv.includes("--output") && process.argv[process.argv.indexOf("--output") + 1] === "json";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senso-ai/cli",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Senso CLI — Infrastructure for the Agentic Web. Interact with your Senso knowledge base from the terminal.",
   "type": "module",
   "bin": {