@senso-ai/cli 0.4.0 → 0.5.0

package/dist/cli.js

@@ -636,13 +636,16 @@ function output(format, data) {
 // src/commands/search.ts
 function registerSearchCommands(program2) {
   const search = program2.command("search").description("Search the knowledge base with natural language queries. Returns AI-generated answers synthesised from matching content chunks, or raw chunks/content IDs.");
-  search.argument("<query>", "Search query").option("--max-results <n>", "Maximum number of results", "5").action(async (query, cmdOpts) => {
+  search.argument("<query>", "Search query").option("--max-results <n>", "Maximum number of 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 (omit to allow fallback to all content)").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",
-        body: { query, max_results: parseInt(cmdOpts.maxResults) },
+        body,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -675,13 +678,16 @@ function registerSearchCommands(program2) {
       process.exit(1);
     }
   });
-  search.command("context <query>").description("Search the knowledge base \u2014 returns matching content chunks only, without AI answer generation. Faster than full search.").option("--max-results <n>", "Maximum results", "5").action(async (query, cmdOpts) => {
+  search.command("context <query>").description("Search the knowledge base \u2014 returns matching content chunks only, without AI answer generation. Use this to feed verified chunks into your own LLM pipeline instead of using Senso's generated answer.").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/context",
-        body: { query, max_results: parseInt(cmdOpts.maxResults) },
+        body,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -691,13 +697,16 @@ function registerSearchCommands(program2) {
       process.exit(1);
     }
   });
-  search.command("content <query>").description("Search the knowledge base \u2014 returns deduplicated content IDs and titles only. No chunks or AI answer.").option("--max-results <n>", "Maximum results", "5").action(async (query, cmdOpts) => {
+  search.command("content <query>").description("Search the knowledge base \u2014 returns deduplicated content IDs and titles only. Use this to discover which documents are relevant before fetching full content with 'content get <id>'.").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/content",
-        body: { query, max_results: parseInt(cmdOpts.maxResults) },
+        body,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -767,7 +776,7 @@ async function uploadToS3(url, buffer, contentType) {
 }
 function registerIngestCommands(program2) {
   const ingest = program2.command("ingest").description("Ingest files into the knowledge base. Upload documents (PDF, TXT, DOCX, etc.) to be parsed, chunked, and embedded for semantic search.");
-  ingest.command("upload <files...>").description("Upload files to the knowledge base. Accepts local file paths (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker.").action(async (files) => {
+  ingest.command("upload <files...>").description("Upload files to the knowledge base. Accepts local file paths (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker. Poll 'senso content get <content-id>' until processing_status is 'complete' before searching the uploaded content.").action(async (files) => {
     const opts = program2.opts();
     if (files.length > 10) {
       error("Maximum 10 files per upload request.");
@@ -1000,7 +1009,7 @@ function registerGenerateCommands(program2) {
       process.exit(1);
     }
   });
-  gen.command("sample").description("Generate an ad hoc content sample for a specific prompt and content type. Returns the generated markdown, SEO title, and publish results.").requiredOption("--prompt-id <id>", "Prompt (geo question) ID to generate content for").requiredOption("--content-type-id <id>", "Content type ID that defines the output format").option("--destination <dest>", "Publish destination (e.g. citeables)").action(async (cmdOpts) => {
+  gen.command("sample").description("Generate an ad hoc content sample for a specific prompt and content type. Returns the generated markdown, SEO title, and publish results. Use 'prompts list' to find a prompt ID, and 'content-types list' to find a content-type ID.").requiredOption("--prompt-id <id>", "Prompt (geo question) ID to generate content for").requiredOption("--content-type-id <id>", "Content type ID that defines the output format (use 'content-types list' to find)").option("--destination <dest>", "Publisher slug to publish to immediately after generation. Omit to save as draft only.").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = {
@@ -1023,7 +1032,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.").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 '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) => {
     const opts = program2.opts();
     try {
       const body = cmdOpts.promptIds ? { prompt_ids: cmdOpts.promptIds } : void 0;
@@ -1091,7 +1100,7 @@ function registerBrandKitCommands(program2) {
       process.exit(1);
     }
   });
-  bk.command("set").description("Create or replace the brand kit. The guidelines field is a free-form JSON object defining your brand voice.").requiredOption("--data <json>", 'JSON: { "guidelines": { "tone": "professional", "voice": "..." } }').action(async (cmdOpts) => {
+  bk.command("set").description("Replace the entire brand kit (PUT). All existing fields are overwritten \u2014 run 'brand-kit get' first to preserve fields you are not changing. For a safe partial update, use 'brand-kit patch'.").requiredOption("--data <json>", 'JSON: { "guidelines": { "brand_name": "Acme", "voice_and_tone": "...", "author_persona": "...", "global_writing_rules": [] } }').action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = JSON.parse(cmdOpts.data);
@@ -1109,6 +1118,24 @@ function registerBrandKitCommands(program2) {
       process.exit(1);
     }
   });
+  bk.command("patch").description("Partially update the brand kit (PATCH). Only the fields you provide are changed \u2014 existing fields are preserved. Preferred over 'set' for targeted updates.").requiredOption("--data <json>", 'JSON: { "guidelines": { "voice_and_tone": "Warm and approachable" } }').action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({
+        method: "PATCH",
+        path: "/org/brand-kit",
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      success("Brand kit updated.");
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/content-types.ts
@@ -1157,7 +1184,7 @@ function registerContentTypeCommands(program2) {
       process.exit(1);
     }
   });
-  ct.command("update <id>").description("Update a content type's name or configuration.").requiredOption("--data <json>", 'JSON: { "name": "Updated Name", "config": { ... } }').action(async (id, cmdOpts) => {
+  ct.command("update <id>").description("Replace a content type's name and config (PUT). Both fields are required \u2014 run 'get <id>' first to preserve existing values. For single-field updates, use 'content-types patch <id>'.").requiredOption("--data <json>", 'JSON: { "name": "Updated Name", "config": { "template": "...", "cta_text": "...", "cta_destination": "...", "writing_rules": [] } }').action(async (id, cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = JSON.parse(cmdOpts.data);
@@ -1175,6 +1202,24 @@ function registerContentTypeCommands(program2) {
       process.exit(1);
     }
   });
+  ct.command("patch <id>").description("Partially update a content type (PATCH). Only the fields you provide are changed \u2014 existing fields are preserved. Preferred over 'update' for targeted changes like updating just the template.").requiredOption("--data <json>", 'JSON: { "config": { "template": "Updated template instruction" } }').action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({
+        method: "PATCH",
+        path: `/org/content-types/${id}`,
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      success(`Content type ${id} updated.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
   ct.command("delete <id>").description("Delete a content type. This cannot be undone.").action(async (id) => {
     const opts = program2.opts();
     try {
@@ -1189,7 +1234,7 @@ function registerContentTypeCommands(program2) {
 
 // src/commands/prompts.ts
 function registerPromptCommands(program2) {
-  const prompts = program2.command("prompts").description("Manage prompts (geo questions). Prompts are the questions that drive AI content generation \u2014 each prompt is run against configured AI models to track brand mentions, claims, and competitor visibility.");
+  const prompts = program2.command("prompts").description("Manage prompts (GEO questions). Each prompt is a question that drives both AI content generation (use with 'generate sample --prompt-id') and brand visibility monitoring \u2014 tracking how AI models mention your brand, products, and competitors.");
   prompts.command("list").description("List all prompts in the organization. Use --search to filter by question text, --sort to order results.").option("--limit <n>", "Maximum prompts to return (max: 100)").option("--offset <n>", "Number of prompts to skip (for pagination)").option("--search <query>", "Filter prompts by question text").option("--sort <order>", "Sort order: created_desc, created_asc, text_asc, text_desc, type_asc, type_desc").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
@@ -1365,6 +1410,21 @@ 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 () => {
+    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/update.ts
 import semver2 from "semver";
 import pc7 from "picocolors";
@@ -1423,6 +1483,7 @@ registerPromptCommands(program);
 registerRunConfigCommands(program);
 registerMemberCommands(program);
 registerNotificationCommands(program);
+registerCreditsCommands(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.4.0",
+  "version": "0.5.0",
   "description": "Senso CLI — Infrastructure for the Agentic Web. Interact with your Senso knowledge base from the terminal.",
   "type": "module",
   "bin": {