@cargo-ai/cli 1.0.7 → 1.0.9

package/build/commands/ai/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/agent.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,CAiIN"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/agent.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,CAoJN"}

package/build/commands/ai/agent.js

@@ -1,6 +1,8 @@
 import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerAgentCommands(parent, getApi) {
-    const agent = parent.command("agent").description("Agent operations");
+    const agent = parent
+        .command("agent")
+        .description("Manage AI agents (list, get, create, update, remove)");
     agent
         .command("list")
         .description("List all agents")
@@ -20,12 +22,20 @@ export function registerAgentCommands(parent, getApi) {
     agent
         .command("create")
         .description("Create an agent")
-        .requiredOption("--name <name>", "Agent name")
-        .requiredOption("--icon-color <color>", "Icon color (grey, green, purple, yellow, blue, red)")
-        .requiredOption("--icon-face <face>", "Icon face identifier")
-        .option("--description <text>", "Agent description")
-        .option("--folder-uuid <uuid>", "Folder UUID")
-        .option("--triggers <json>", 'Triggers (JSON array, e.g. [{"name":"Daily","type":"cron","cron":"0 9 * * *","text":"Run daily","description":null}])')
+        .requiredOption("--name <name>", "Agent name (string, required)")
+        .requiredOption("--icon-color <color>", "Icon color (string, required). Allowed values: grey, green, purple, yellow, blue, red")
+        .requiredOption("--icon-face <face>", "Icon face identifier (string, required)")
+        .option("--description <text>", "Agent description (string)")
+        .option("--folder-uuid <uuid>", "Folder UUID to place the agent in (string)")
+        .option("--triggers <json>", "Triggers configuration (JSON array of trigger objects)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai agent create --name "My Agent" --icon-color blue --icon-face robot
+  $ cargo-ai ai agent create --name "Daily Sync" --icon-color green --icon-face robot \\
+      --triggers '[{"name":"Daily","type":"cron","cron":"0 9 * * *","text":"Run daily","description":null}]'
+
+Trigger object shape:
+  { "name": string, "type": "cron", "cron": string, "text": string, "description": string | null }`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.agent.create({
@@ -53,13 +63,13 @@ export function registerAgentCommands(parent, getApi) {
     agent
         .command("update")
         .description("Update an agent")
-        .requiredOption("--uuid <uuid>", "Agent UUID")
-        .option("--name <name>", "Agent name")
-        .option("--icon-color <color>", "Icon color (grey, green, purple, yellow, blue, red)")
-        .option("--icon-face <face>", "Icon face identifier")
-        .option("--description <text>", "Agent description")
-        .option("--folder-uuid <uuid>", "Folder UUID")
-        .option("--triggers <json>", 'Triggers (JSON array, e.g. [{"name":"Daily","type":"cron","cron":"0 9 * * *","text":"Run daily","description":null}])')
+        .requiredOption("--uuid <uuid>", "Agent UUID (string, required)")
+        .option("--name <name>", "Agent name (string)")
+        .option("--icon-color <color>", "Icon color (string). Allowed values: grey, green, purple, yellow, blue, red")
+        .option("--icon-face <face>", "Icon face identifier (string)")
+        .option("--description <text>", "Agent description (string)")
+        .option("--folder-uuid <uuid>", "Folder UUID (string)")
+        .option("--triggers <json>", "Triggers configuration (JSON array of trigger objects, same format as 'agent create')")
         .action(async (opts) => {
         const api = getApi();
         const icon = opts.iconColor !== undefined && opts.iconFace !== undefined

package/build/commands/ai/chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAuG7E"}
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAoH7E"}

package/build/commands/ai/chat.js

@@ -1,15 +1,17 @@
 import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerChatCommands(parent, getApi) {
-    const chat = parent.command("chat").description("Chat operations");
+    const chat = parent
+        .command("chat")
+        .description("Manage AI chats (list, get, create, update, remove)");
     chat
         .command("list")
         .description("List chats")
-        .option("--agent-uuid <uuid>", "Agent UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--user-uuid <uuid>", "User UUID")
-        .option("--trigger-type <type>", "Trigger type")
-        .option("--limit <n>", "Limit")
-        .option("--offset <n>", "Offset")
+        .option("--agent-uuid <uuid>", "Filter by agent UUID (string)")
+        .option("--release-uuid <uuid>", "Filter by release UUID (string)")
+        .option("--user-uuid <uuid>", "Filter by user UUID (string)")
+        .option("--trigger-type <type>", "Filter by trigger type (string: chat, draft, cron, ...)")
+        .option("--limit <n>", "Max results to return (integer)")
+        .option("--offset <n>", "Number of results to skip (integer)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.chat.list({
@@ -33,10 +35,18 @@ export function registerChatCommands(parent, getApi) {
     chat
         .command("create")
         .description("Create a chat")
-        .requiredOption("--trigger <json>", 'Chat trigger (JSON, e.g. {"type":"chat","uuid":"...","agentUuid":null,"messageUuid":null} or {"type":"draft"})')
-        .option("--name <name>", "Chat name")
-        .option("--agent-uuid <uuid>", "Agent UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
+        .requiredOption("--trigger <json>", "Chat trigger (JSON object, required)")
+        .option("--name <name>", "Chat name (string)")
+        .option("--agent-uuid <uuid>", "Agent UUID to associate with (string)")
+        .option("--release-uuid <uuid>", "Release UUID to pin to (string)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai chat create --trigger '{"type":"draft"}'
+  $ cargo-ai ai chat create --trigger '{"type":"chat","uuid":"...","agentUuid":null,"messageUuid":null}' --name "My Chat"
+
+Trigger object shapes:
+  Draft:  { "type": "draft" }
+  Chat:   { "type": "chat", "uuid": string, "agentUuid": string | null, "messageUuid": string | null }`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.chat.create({

package/build/commands/ai/mcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/mcpClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAgDN"}
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/mcpClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA4DN"}

package/build/commands/ai/mcpClient.js

@@ -2,14 +2,20 @@ import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerMcpClientCommands(parent, getApi) {
     const mcpClient = parent
         .command("mcp-client")
-        .description("MCP client operations");
+        .description("Connect to external MCP servers");
     mcpClient
         .command("connect")
-        .description("Connect an MCP client")
-        .requiredOption("--name <name>", "MCP client name")
-        .requiredOption("--url <url>", "MCP client URL")
-        .option("--authentication <json>", 'Authentication (JSON or "null", e.g. {"issuedAt":"...","accessToken":"..."})')
-        .option("--disabled-tool-slugs <list>", "Disabled tool slugs (comma-separated)")
+        .description("Connect to an external MCP server")
+        .requiredOption("--name <name>", "MCP client name (string, required)")
+        .requiredOption("--url <url>", "MCP server URL to connect to (string, required)")
+        .option("--authentication <json>", 'Authentication credentials (JSON object or "null"). Shape: {"issuedAt": string, "accessToken": string}')
+        .option("--disabled-tool-slugs <list>", "Tool slugs to disable (comma-separated strings)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai mcp-client connect --name "My MCP" --url https://mcp.example.com/sse
+  $ cargo-ai ai mcp-client connect --name "My MCP" --url https://mcp.example.com/sse \\
+      --authentication '{"issuedAt":"2025-01-01","accessToken":"sk_..."}' \\
+      --disabled-tool-slugs slow-tool,deprecated-tool`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.mcpClient.connect({

package/build/commands/ai/mcpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpServer.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/mcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA6EN"}
+{"version":3,"file":"mcpServer.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/mcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAsHN"}

package/build/commands/ai/mcpServer.js

@@ -2,7 +2,7 @@ import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerMcpServerCommands(parent, getApi) {
     const mcpServer = parent
         .command("mcp-server")
-        .description("MCP server operations");
+        .description("Manage MCP servers (list, get, create, update, remove)");
     mcpServer
         .command("list")
         .description("List all MCP servers")
@@ -22,15 +22,32 @@ export function registerMcpServerCommands(parent, getApi) {
     mcpServer
         .command("create")
         .description("Create an MCP server")
-        .requiredOption("--name <name>", "MCP server name")
-        .option("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","name":null,"description":null,"isBulkAllowed":false,"config":{}}])')
+        .requiredOption("--name <name>", "MCP server name (string, required)")
+        .option("--actions <json>", "Actions to expose (JSON array of action objects, default: [])")
+        .option("--resources <json>", "Resources to expose (JSON array of resource objects, default: [])")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai mcp-server create --name "My Server"
+  $ cargo-ai ai mcp-server create --name "My Server" \\
+      --actions '[{"slug":"my-action","kind":"tool","name":null,"description":null,"isBulkAllowed":false,"config":{}}]' \\
+      --resources '[{"kind":"model","slug":"my-resource","name":"My Resource","description":null,"integrationSlug":"hubspot","modelUuid":null,"filter":null,"selectedColumnSlugs":null,"limit":null,"prompt":null}]'
+
+Action object shape:
+  { "slug": string, "kind": "tool", "name": string | null, "description": string | null, "isBulkAllowed": boolean, "config": object }
+
+Resource object shapes:
+  Model:  { "kind": "model", "slug": string, "name": string, "description": string | null, "integrationSlug": string, "modelUuid": string | null, "filter": object | null, "selectedColumnSlugs": string[] | null, "limit": number | null, "prompt": string | null }
+  File:   { "kind": "file", "slug": string, "name": string, "description": string | null, "items": [{"kind":"file","fileUuid": string}], "prompt": string | null }`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.mcpServer.create({
             name: opts.name,
-            tools: opts.tools !== undefined
-                ? parseJson(opts.tools, "--tools")
-                : undefined,
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
+                : [],
+            resources: opts.resources !== undefined
+                ? parseJson(opts.resources, "--resources")
+                : [],
         }));
         outputJson(result);
     });
@@ -45,16 +62,20 @@ export function registerMcpServerCommands(parent, getApi) {
     mcpServer
         .command("update")
         .description("Update an MCP server")
-        .requiredOption("--uuid <uuid>", "MCP server UUID")
-        .option("--name <name>", "MCP server name")
-        .option("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","name":null,"description":null,"isBulkAllowed":false,"config":{}}])')
+        .requiredOption("--uuid <uuid>", "MCP server UUID (string, required)")
+        .option("--name <name>", "MCP server name (string)")
+        .option("--actions <json>", "Actions to expose (JSON array of action objects, same format as 'mcp-server create')")
+        .option("--resources <json>", "Resources to expose (JSON array of resource objects, same format as 'mcp-server create')")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.mcpServer.update({
             uuid: opts.uuid,
             name: opts.name,
-            tools: opts.tools !== undefined
-                ? parseJson(opts.tools, "--tools")
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
+                : undefined,
+            resources: opts.resources !== undefined
+                ? parseJson(opts.resources, "--resources")
                 : undefined,
         }));
         outputJson(result);

package/build/commands/ai/message.d.ts.map

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

package/build/commands/ai/message.js

@@ -1,31 +1,43 @@
 import { handleApiCall, outputJson, parseJson, pollMessageUntilFinished, } from "../runHandler.js";
 export function registerMessageCommands(parent, getApi) {
-    const message = parent.command("message").description("Message operations");
+    const message = parent
+        .command("message")
+        .description("Manage chat messages (create, get, list, cancel, remove)");
     message
         .command("create")
         .description("Create a message in a chat. Returns the user message and a pending assistant message.")
-        .requiredOption("--chat-uuid <uuid>", "Chat UUID")
-        .requiredOption("--parts <json>", 'Message parts (JSON array, e.g. [{"type":"text","text":"Hello"}])')
-        .option("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","config":{}}])')
-        .option("--resources <json>", 'Resources (JSON array, e.g. [{"slug":"my-resource","kind":"model","modelUuid":"..."}])')
-        .option("--capabilities <json>", 'Capabilities (JSON array, e.g. [{"slug":"web-browsing"}])')
-        .option("--mcp-clients <json>", 'MCP clients (JSON array, e.g. [{"name":"my-mcp","url":"..."}])')
-        .option("--system-prompt <text>", "System prompt")
-        .option("--with-reasoning", "Enable reasoning")
-        .option("--temperature <n>", "Sampling temperature")
-        .option("--max-steps <n>", "Maximum number of steps")
-        .option("--integration-slug <slug>", "Integration slug")
-        .option("--connector-uuid <uuid>", "Connector UUID")
-        .option("--language-model-slug <slug>", "Language model slug")
-        .option("--wait-until-finished", "Poll the assistant message until it reaches a terminal status before returning")
-        .option("--polling-interval <ms>", "Polling interval in milliseconds (used with --wait-until-finished)", "5000")
+        .requiredOption("--chat-uuid <uuid>", "Chat UUID (string, required)")
+        .requiredOption("--parts <json>", "Message parts (JSON array of part objects, required)")
+        .option("--actions <json>", "Actions available to the assistant (JSON array of action objects)")
+        .option("--resources <json>", "Resources available to the assistant (JSON array of resource objects)")
+        .option("--capabilities <json>", "Capabilities to enable (JSON array of capability objects)")
+        .option("--mcp-clients <json>", "MCP clients to connect (JSON array of MCP client objects)")
+        .option("--system-prompt <text>", "System prompt override (string)")
+        .option("--with-reasoning", "Enable reasoning mode (boolean flag)")
+        .option("--temperature <n>", "Sampling temperature (float, 0.0-1.0)")
+        .option("--max-steps <n>", "Maximum number of agentic steps (integer)")
+        .option("--integration-slug <slug>", "Integration slug (string)")
+        .option("--connector-uuid <uuid>", "Connector UUID (string)")
+        .option("--language-model-slug <slug>", "Language model slug (string)")
+        .option("--wait-until-finished", "Poll the assistant message until finished before returning (boolean flag)")
+        .option("--polling-interval <ms>", "Polling interval in milliseconds, used with --wait-until-finished (integer, default: 5000)", "5000")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai message create --chat-uuid 550e8400-... --parts '[{"type":"text","text":"Hello"}]'
+  $ cargo-ai ai message create --chat-uuid 550e8400-... --parts '[{"type":"text","text":"Find leads"}]' \\
+      --actions '[{"slug":"search","kind":"tool","config":{}}]' --wait-until-finished
+
+Part object shape:     { "type": "text", "text": string }
+Action object shape:   { "slug": string, "kind": "tool", "config": object }
+Resource object shape: { "slug": string, "kind": "model", "modelUuid": string }
+MCP client shape:      { "name": string, "url": string }`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.message.create({
             chatUuid: opts.chatUuid,
             parts: parseJson(opts.parts, "--parts"),
-            tools: opts.tools !== undefined
-                ? parseJson(opts.tools, "--tools")
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
                 : undefined,
             resources: opts.resources !== undefined
                 ? parseJson(opts.resources, "--resources")
@@ -67,9 +79,9 @@ export function registerMessageCommands(parent, getApi) {
     message
         .command("list")
         .description("List messages")
-        .requiredOption("--chat-uuid <uuid>", "Chat UUID")
-        .option("--limit <n>", "Limit")
-        .option("--offset <n>", "Offset")
+        .requiredOption("--chat-uuid <uuid>", "Chat UUID (string, required)")
+        .option("--limit <n>", "Max results to return (integer)")
+        .option("--offset <n>", "Number of results to skip (integer)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.message.list({
@@ -79,6 +91,16 @@ export function registerMessageCommands(parent, getApi) {
         }));
         outputJson(result);
     });
+    message
+        .command("cancel")
+        .description("Cancel one or more messages by UUID")
+        .requiredOption("--uuids <uuids>", "Message UUIDs to cancel (comma-separated strings, required)")
+        .action(async (opts) => {
+        const api = getApi();
+        const uuids = opts.uuids.split(",").map((u) => u.trim());
+        await handleApiCall(() => api.ai.message.cancel({ uuids }));
+        outputJson({ ok: true });
+    });
     message
         .command("remove <uuid>")
         .description("Remove a message")

package/build/commands/ai/prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAyDN"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAmFN"}

package/build/commands/ai/prompt.js

@@ -1,10 +1,15 @@
 import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerPromptCommands(parent, getApi) {
-    const prompt = parent.command("prompt").description("Prompt operations");
+    const prompt = parent
+        .command("prompt")
+        .description("Optimize and evaluate AI prompts");
     prompt
         .command("optimize")
-        .description("Optimize a prompt")
-        .requiredOption("--prompt <text>", "Prompt text to optimize")
+        .description("Optimize a prompt for better AI performance")
+        .requiredOption("--prompt <text>", "Prompt text to optimize (string, required)")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai ai prompt optimize --prompt "Find me all companies in San Francisco"`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.prompt.optimize({ prompt: opts.prompt }));
@@ -12,16 +17,25 @@ export function registerPromptCommands(parent, getApi) {
     });
     prompt
         .command("evaluate")
-        .description("Evaluate a prompt")
-        .requiredOption("--prompt <text>", "Prompt text to evaluate")
-        .option("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","config":{}}])')
-        .option("--resources <json>", 'Resources (JSON array, e.g. [{"slug":"my-resource","kind":"model","modelUuid":"..."}])')
-        .option("--capabilities <json>", 'Capabilities (JSON array, e.g. [{"slug":"web-browsing"}])')
+        .description("Evaluate a prompt's quality and get scoring feedback")
+        .requiredOption("--prompt <text>", "Prompt text to evaluate (string, required)")
+        .option("--actions <json>", "Available actions context (JSON array of action objects, default: [])")
+        .option("--resources <json>", "Available resources context (JSON array of resource objects, default: [])")
+        .option("--capabilities <json>", "Available capabilities context (JSON array of capability objects, default: [])")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai prompt evaluate --prompt "Find me all companies in San Francisco"
+  $ cargo-ai ai prompt evaluate --prompt "Enrich this lead" \\
+      --actions '[{"slug":"my-action","kind":"tool","config":{}}]' \\
+      --resources '[{"slug":"my-resource","kind":"model","modelUuid":"..."}]' \\
+      --capabilities '[{"slug":"web-browsing"}]'`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.prompt.evaluate({
             prompt: opts.prompt,
-            tools: opts.tools !== undefined ? parseJson(opts.tools, "--tools") : [],
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
+                : [],
             resources: opts.resources !== undefined
                 ? parseJson(opts.resources, "--resources")
                 : [],

package/build/commands/ai/release.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/release.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,CA8PN"}
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/release.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,CA0QN"}

package/build/commands/ai/release.js

@@ -2,15 +2,15 @@ import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerReleaseCommands(parent, getApi) {
     const release = parent
         .command("release")
-        .description("AI release operations");
+        .description("Manage AI agent releases (list, get, draft, deploy)");
     release
         .command("list")
         .description("List AI releases")
-        .option("--agent-uuid <uuid>", "Agent UUID")
-        .option("--user-uuid <uuid>", "User UUID")
-        .option("--statuses <statuses>", "Statuses (comma-separated)")
-        .option("--limit <n>", "Limit")
-        .option("--offset <n>", "Offset")
+        .option("--agent-uuid <uuid>", "Filter by agent UUID (string)")
+        .option("--user-uuid <uuid>", "Filter by user UUID (string)")
+        .option("--statuses <statuses>", "Filter by statuses (comma-separated: draft,deployed,archived)")
+        .option("--limit <n>", "Max results to return (integer)")
+        .option("--offset <n>", "Number of results to skip (integer)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.release.list({
@@ -43,22 +43,22 @@ export function registerReleaseCommands(parent, getApi) {
     });
     release
         .command("update-draft")
-        .description("Update draft AI release")
-        .requiredOption("--agent-uuid <uuid>", "Agent UUID")
-        .option("--parent-uuid <uuid>", "Parent release UUID")
-        .option("--system-prompt <text>", "System prompt")
-        .option("--with-reasoning", "Enable reasoning")
-        .option("--temperature <n>", "Temperature")
-        .option("--max-steps <n>", "Max steps")
-        .option("--integration-slug <slug>", "Integration slug")
-        .option("--connector-uuid <uuid>", "Connector UUID")
-        .option("--language-model-slug <slug>", "Language model slug")
-        .option("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","config":{}}])')
-        .option("--mcp-clients <json>", 'MCP clients (JSON array, e.g. [{"name":"client","url":"https://...","authentication":null,"disabledToolSlugs":[]}])')
-        .option("--resources <json>", 'Resources (JSON array, e.g. [{"slug":"my-resource","kind":"model","modelUuid":"..."}])')
-        .option("--capabilities <json>", 'Capabilities (JSON array, e.g. [{"slug":"web-browsing"}])')
-        .option("--suggested-actions <json>", 'Suggested actions (JSON array, e.g. [{"text":"Summarize","tools":[{"slug":"..."}]}])')
-        .option("--options <json>", "Options (JSON object)")
+        .description("Update draft AI release configuration")
+        .requiredOption("--agent-uuid <uuid>", "Agent UUID (string, required)")
+        .option("--parent-uuid <uuid>", "Parent release UUID to inherit from (string)")
+        .option("--system-prompt <text>", "System prompt (string)")
+        .option("--with-reasoning", "Enable reasoning mode (boolean flag)")
+        .option("--temperature <n>", "Sampling temperature (float, 0.0-1.0)")
+        .option("--max-steps <n>", "Maximum agentic steps (integer)")
+        .option("--integration-slug <slug>", "LLM integration slug (string)")
+        .option("--connector-uuid <uuid>", "Connector UUID (string)")
+        .option("--language-model-slug <slug>", "Language model slug (string)")
+        .option("--actions <json>", "Actions configuration (JSON array of action objects)")
+        .option("--mcp-clients <json>", "MCP clients configuration (JSON array of MCP client objects)")
+        .option("--resources <json>", "Resources configuration (JSON array of resource objects)")
+        .option("--capabilities <json>", "Capabilities to enable (JSON array of capability objects)")
+        .option("--suggested-actions <json>", "Suggested actions for the chat UI (JSON array of action objects)")
+        .option("--options <json>", "Additional options (JSON object)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.release.updateDraft({
@@ -75,8 +75,8 @@ export function registerReleaseCommands(parent, getApi) {
             integrationSlug: opts.integrationSlug,
             connectorUuid: opts.connectorUuid,
             languageModelSlug: opts.languageModelSlug,
-            tools: opts.tools !== undefined
-                ? parseJson(opts.tools, "--tools")
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
                 : undefined,
             mcpClients: opts.mcpClients !== undefined
                 ? parseJson(opts.mcpClients, "--mcp-clients")
@@ -98,23 +98,23 @@ export function registerReleaseCommands(parent, getApi) {
     });
     release
         .command("deploy-draft")
-        .description("Deploy draft AI release")
-        .requiredOption("--agent-uuid <uuid>", "Agent UUID")
-        .requiredOption("--integration-slug <slug>", "Integration slug")
-        .requiredOption("--language-model-slug <slug>", "Language model slug")
-        .option("--version <version>", "Release version (e.g. '1.0.0', '1.1.0', '1.0.1', etc.)")
-        .requiredOption("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","config":{}}])')
-        .requiredOption("--mcp-clients <json>", 'MCP clients (JSON array, e.g. [{"name":"client","url":"https://...","authentication":null,"disabledToolSlugs":[]}])')
-        .requiredOption("--resources <json>", 'Resources (JSON array, e.g. [{"slug":"my-resource","kind":"model","modelUuid":"..."}])')
-        .requiredOption("--capabilities <json>", 'Capabilities (JSON array, e.g. [{"slug":"web-browsing"}])')
-        .requiredOption("--suggested-actions <json>", 'Suggested actions (JSON array, e.g. [{"text":"Summarize","tools":[{"slug":"..."}]}])')
-        .option("--system-prompt <text>", "System prompt")
-        .option("--with-reasoning", "Enable reasoning")
-        .option("--temperature <n>", "Temperature")
-        .option("--max-steps <n>", "Max steps")
-        .option("--connector-uuid <uuid>", "Connector UUID")
-        .option("--description <text>", "Release description")
-        .option("--options <json>", "Options (JSON)")
+        .description("Deploy the draft release to production")
+        .requiredOption("--agent-uuid <uuid>", "Agent UUID (string, required)")
+        .requiredOption("--integration-slug <slug>", "LLM integration slug (string, required)")
+        .requiredOption("--language-model-slug <slug>", "Language model slug (string, required)")
+        .option("--version <version>", "Semver release version, e.g. 1.0.0 (string, auto-incremented if omitted)")
+        .requiredOption("--actions <json>", "Actions configuration (JSON array of action objects, required)")
+        .requiredOption("--mcp-clients <json>", "MCP clients configuration (JSON array, required)")
+        .requiredOption("--resources <json>", "Resources configuration (JSON array, required)")
+        .requiredOption("--capabilities <json>", "Capabilities to enable (JSON array, required)")
+        .requiredOption("--suggested-actions <json>", "Suggested actions for chat UI (JSON array, required)")
+        .option("--system-prompt <text>", "System prompt (string)")
+        .option("--with-reasoning", "Enable reasoning mode (boolean flag)")
+        .option("--temperature <n>", "Sampling temperature (float, 0.0-1.0)")
+        .option("--max-steps <n>", "Maximum agentic steps (integer)")
+        .option("--connector-uuid <uuid>", "Connector UUID (string)")
+        .option("--description <text>", "Release description (string)")
+        .option("--options <json>", "Additional options (JSON object)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.release.deployDraft({
@@ -122,7 +122,7 @@ export function registerReleaseCommands(parent, getApi) {
             integrationSlug: opts.integrationSlug,
             languageModelSlug: opts.languageModelSlug,
             version: opts.version,
-            tools: parseJson(opts.tools, "--tools"),
+            actions: parseJson(opts.actions, "--actions"),
             mcpClients: parseJson(opts.mcpClients, "--mcp-clients"),
             resources: parseJson(opts.resources, "--resources"),
             capabilities: parseJson(opts.capabilities, "--capabilities"),

package/build/commands/ai/suggestedAction.js

@@ -10,7 +10,7 @@ export function registerSuggestedActionCommands(parent, getApi) {
         .option("--system-prompt <text>", "System prompt")
         .option("--context-prompt <text>", "Context prompt")
         .option("--agent-uuid <uuid>", "Agent UUID")
-        .option("--tools <json>", 'Tools (JSON array, e.g. [{"slug":"my-tool","kind":"tool","config":{}}])')
+        .option("--actions <json>", 'Actions (JSON array, e.g. [{"slug":"my-action","kind":"tool","config":{}}])')
         .option("--resources <json>", 'Resources (JSON array, e.g. [{"slug":"my-resource","kind":"model","modelUuid":"..."}])')
         .option("--capabilities <json>", 'Capabilities (JSON array, e.g. [{"slug":"web-browsing"}])')
         .option("--cache-key <key>", "Cache key")
@@ -21,8 +21,8 @@ export function registerSuggestedActionCommands(parent, getApi) {
             systemPrompt: opts.systemPrompt,
             contextPrompt: opts.contextPrompt,
             agentUuid: opts.agentUuid,
-            tools: opts.tools !== undefined
-                ? parseJson(opts.tools, "--tools")
+            actions: opts.actions !== undefined
+                ? parseJson(opts.actions, "--actions")
                 : undefined,
             resources: opts.resources !== undefined
                 ? parseJson(opts.resources, "--resources")

package/build/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAWrC,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAgHN"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAWrC,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAuIN"}

package/build/commands/auth.js

@@ -5,9 +5,17 @@ export function registerAuthCommands(program, getApi) {
     program
         .command("login")
         .description("Save API credentials for future use")
-        .requiredOption("--token <token>", "Cargo API token")
-        .option("--workspace-uuid <uuid>", "Default workspace UUID")
-        .option("--base-url <url>", `API base URL (default: ${DEFAULT_BASE_URL})`)
+        .requiredOption("--token <token>", "Cargo API token (string)")
+        .option("--workspace-uuid <uuid>", "Default workspace UUID (string, UUID v4)")
+        .option("--base-url <url>", `API base URL (string, default: ${DEFAULT_BASE_URL})`)
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai login --token sk_live_abc123
+  $ cargo-ai login --token sk_live_abc123 --workspace-uuid 550e8400-e29b-41d4-a716-446655440000
+  $ cargo-ai login --token sk_live_abc123 --base-url https://api.custom.io
+
+Credentials are stored in ~/.config/cargo-ai/credentials.json.
+Environment variables (CARGO_API_TOKEN, CARGO_WORKSPACE_UUID, CARGO_BASE_URL) take precedence over saved credentials.`)
         .action((opts) => {
         saveCredentials({
             accessToken: opts.token,
@@ -35,6 +43,9 @@ export function registerAuthCommands(program, getApi) {
     program
         .command("whoami")
         .description("Show current user and workspace")
+        .addHelpText("after", `
+Returns JSON with: user (uuid, email, name), workspace (uuid, name),
+authentication source ("environment" or "credentials-file"), and base URL.`)
         .action(async () => {
         const envToken = process.env["CARGO_API_TOKEN"];
         const envBaseUrl = process.env["CARGO_BASE_URL"];

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

@@ -1 +1 @@
-{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAkNN"}
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAoPN"}