@cargo-ai/cli 1.0.7 → 1.0.9

package/build/commands/orchestration/run.js

@@ -1,26 +1,33 @@
 import { handleApiCall, outputJson, parseJson, pollRunUntilFinished, } from "../runHandler.js";
 export function registerRunCommands(parent, getApi) {
-    const run = parent.command("run").description("Run operations");
+    const run = parent
+        .command("run")
+        .description("Manage workflow runs (list, get, create, cancel, count, download)");
     run
         .command("list")
         .description("List runs")
-        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID")
-        .option("--batch-uuid <uuid>", "Batch UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--statuses <list>", "Statuses (comma-separated)")
-        .option("--parent-batch-uuid <uuid>", "Parent batch UUID")
-        .option("--parent-uuid <uuid>", "Parent run UUID")
-        .option("--parent-node-uuid <uuid>", "Parent node UUID")
-        .option("--is-group-parent", "Only group parents")
-        .option("--record-id <id>", "Record ID")
-        .option("--record-title <title>", "Record title")
-        .option("--record-title-or-id <value>", "Record title or ID")
-        .option("--is-finished", "Only finished runs")
-        .option("--executions-filter <json>", 'Executions filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"node","nodeSlug":"...","operator":"isRunning"}]}]})')
-        .option("--created-after <date>", "Created after date")
-        .option("--created-before <date>", "Created before date")
-        .option("--limit <n>", "Limit", "20")
-        .option("--offset <n>", "Offset", "0")
+        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID (string, required)")
+        .option("--batch-uuid <uuid>", "Filter by batch UUID (string)")
+        .option("--release-uuid <uuid>", "Filter by release UUID (string)")
+        .option("--statuses <list>", "Filter by statuses (comma-separated: pending,running,finished,failed,cancelled)")
+        .option("--parent-batch-uuid <uuid>", "Filter by parent batch UUID (string)")
+        .option("--parent-uuid <uuid>", "Filter by parent run UUID (string)")
+        .option("--parent-node-uuid <uuid>", "Filter by parent node UUID (string)")
+        .option("--is-group-parent", "Only return group parents (boolean flag)")
+        .option("--record-id <id>", "Filter by record ID (string)")
+        .option("--record-title <title>", "Filter by record title (string)")
+        .option("--record-title-or-id <value>", "Filter by record title or ID (string)")
+        .option("--is-finished", "Only return finished runs (boolean flag)")
+        .option("--executions-filter <json>", 'Filter by node executions (JSON object). Example: \'{"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"node","nodeSlug":"my-node","operator":"isRunning"}]}]}\'')
+        .option("--created-after <date>", "Filter runs created after this date (ISO 8601 string)")
+        .option("--created-before <date>", "Filter runs created before this date (ISO 8601 string)")
+        .option("--limit <n>", "Max results to return (integer, default: 20)", "20")
+        .option("--offset <n>", "Number of results to skip (integer, default: 0)", "0")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai orchestration run list --workflow-uuid 550e8400-...
+  $ cargo-ai orchestration run list --workflow-uuid 550e8400-... --statuses running,pending --limit 50
+  $ cargo-ai orchestration run list --workflow-uuid 550e8400-... --created-after 2025-01-01T00:00:00Z`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.run.list({
@@ -59,12 +66,17 @@ export function registerRunCommands(parent, getApi) {
     run
         .command("create")
         .description("Create a run")
-        .option("--workflow-uuid <uuid>", "Workflow UUID")
-        .requiredOption("--data <json>", "Run data (JSON, e.g. {...})")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--nodes <json>", 'Custom nodes to override the workflow definition (JSON array). Must include a start node (slug:"start") and an end node (slug:"end"). E.g. [{"uuid":"a","slug":"start","kind":"native","actionSlug":"start","config":{},"childrenUuids":["b"],"fallbackOnFailure":false,"position":{"x":0,"y":0}},{"uuid":"b","slug":"end","kind":"native","actionSlug":"end","config":{},"childrenUuids":[],"fallbackOnFailure":false,"position":{"x":1,"y":0}}]')
-        .option("--wait-until-finished", "Poll the run until it reaches a terminal status before returning")
-        .option("--polling-interval <ms>", "Polling interval in milliseconds (used with --wait-until-finished)", "5000")
+        .option("--workflow-uuid <uuid>", "Workflow UUID (string)")
+        .requiredOption("--data <json>", "Run input data (JSON object, required). The shape depends on your workflow's start node configuration")
+        .option("--release-uuid <uuid>", "Release UUID to pin the run to (string)")
+        .option("--nodes <json>", 'Custom nodes to override the workflow definition (JSON array). Must include a start node (slug:"start") and an end node (slug:"end")')
+        .option("--wait-until-finished", "Poll the run until it reaches a terminal status 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 orchestration run create --data '{"email":"user@example.com"}'
+  $ cargo-ai orchestration run create --workflow-uuid 550e8400-... --data '{"id":"123"}' --wait-until-finished
+  $ cargo-ai orchestration run create --data '{"id":"123"}' --wait-until-finished --polling-interval 10000`)
         .action(async (opts) => {
         const data = parseJson(opts.data, "--data");
         const api = getApi();
@@ -87,8 +99,12 @@ export function registerRunCommands(parent, getApi) {
     run
         .command("cancel")
         .description("Cancel runs")
-        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID")
-        .option("--uuids <list>", "Run UUIDs (comma-separated)")
+        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID (string, required)")
+        .option("--uuids <list>", "Run UUIDs to cancel (comma-separated strings). Omit to cancel all runs in the workflow")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai orchestration run cancel --workflow-uuid 550e8400-...
+  $ cargo-ai orchestration run cancel --workflow-uuid 550e8400-... --uuids uuid1,uuid2`)
         .action(async (opts) => {
         const api = getApi();
         const payload = opts.uuids !== undefined
@@ -102,22 +118,22 @@ export function registerRunCommands(parent, getApi) {
     });
     run
         .command("count")
-        .description("Count runs")
-        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID")
-        .option("--batch-uuid <uuid>", "Batch UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--statuses <list>", "Statuses (comma-separated)")
-        .option("--parent-batch-uuid <uuid>", "Parent batch UUID")
-        .option("--parent-uuid <uuid>", "Parent run UUID")
-        .option("--parent-node-uuid <uuid>", "Parent node UUID")
-        .option("--is-group-parent", "Only group parents")
-        .option("--record-id <id>", "Record ID")
-        .option("--record-title <title>", "Record title")
-        .option("--record-title-or-id <value>", "Record title or ID")
-        .option("--is-finished", "Only finished runs")
-        .option("--executions-filter <json>", 'Executions filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"node","nodeSlug":"...","operator":"isRunning"}]}]})')
-        .option("--created-after <date>", "Created after date")
-        .option("--created-before <date>", "Created before date")
+        .description("Count runs matching the given filters")
+        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID (string, required)")
+        .option("--batch-uuid <uuid>", "Filter by batch UUID (string)")
+        .option("--release-uuid <uuid>", "Filter by release UUID (string)")
+        .option("--statuses <list>", "Filter by statuses (comma-separated: pending,running,finished,failed,cancelled)")
+        .option("--parent-batch-uuid <uuid>", "Filter by parent batch UUID (string)")
+        .option("--parent-uuid <uuid>", "Filter by parent run UUID (string)")
+        .option("--parent-node-uuid <uuid>", "Filter by parent node UUID (string)")
+        .option("--is-group-parent", "Only count group parents (boolean flag)")
+        .option("--record-id <id>", "Filter by record ID (string)")
+        .option("--record-title <title>", "Filter by record title (string)")
+        .option("--record-title-or-id <value>", "Filter by record title or ID (string)")
+        .option("--is-finished", "Only count finished runs (boolean flag)")
+        .option("--executions-filter <json>", "Filter by node executions (JSON object, same format as 'run list')")
+        .option("--created-after <date>", "Filter runs created after this date (ISO 8601 string)")
+        .option("--created-before <date>", "Filter runs created before this date (ISO 8601 string)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.run.count({
@@ -145,22 +161,22 @@ export function registerRunCommands(parent, getApi) {
     });
     run
         .command("download")
-        .description("Download run results")
-        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID")
-        .option("--batch-uuid <uuid>", "Batch UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--statuses <list>", "Statuses (comma-separated)")
-        .option("--parent-batch-uuid <uuid>", "Parent batch UUID")
-        .option("--parent-uuid <uuid>", "Parent run UUID")
-        .option("--parent-node-uuid <uuid>", "Parent node UUID")
-        .option("--is-group-parent", "Only group parents")
-        .option("--record-id <id>", "Record ID")
-        .option("--record-title <title>", "Record title")
-        .option("--record-title-or-id <value>", "Record title or ID")
-        .option("--is-finished", "Only finished runs")
-        .option("--executions-filter <json>", 'Executions filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"node","nodeSlug":"...","operator":"isRunning"}]}]})')
-        .option("--created-after <date>", "Created after date")
-        .option("--created-before <date>", "Created before date")
+        .description("Download run results as JSON")
+        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID (string, required)")
+        .option("--batch-uuid <uuid>", "Filter by batch UUID (string)")
+        .option("--release-uuid <uuid>", "Filter by release UUID (string)")
+        .option("--statuses <list>", "Filter by statuses (comma-separated: pending,running,finished,failed,cancelled)")
+        .option("--parent-batch-uuid <uuid>", "Filter by parent batch UUID (string)")
+        .option("--parent-uuid <uuid>", "Filter by parent run UUID (string)")
+        .option("--parent-node-uuid <uuid>", "Filter by parent node UUID (string)")
+        .option("--is-group-parent", "Only return group parents (boolean flag)")
+        .option("--record-id <id>", "Filter by record ID (string)")
+        .option("--record-title <title>", "Filter by record title (string)")
+        .option("--record-title-or-id <value>", "Filter by record title or ID (string)")
+        .option("--is-finished", "Only return finished runs (boolean flag)")
+        .option("--executions-filter <json>", "Filter by node executions (JSON object, same format as 'run list')")
+        .option("--created-after <date>", "Filter runs created after this date (ISO 8601 string)")
+        .option("--created-before <date>", "Filter runs created before this date (ISO 8601 string)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.run.download({
@@ -188,24 +204,29 @@ export function registerRunCommands(parent, getApi) {
     });
     run
         .command("download-outputs")
-        .description("Download run outputs")
-        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID")
-        .requiredOption("--output-node-slug <slug>", "Output node slug")
-        .option("--format <format>", "Export format (csv or json)", "csv")
-        .option("--batch-uuid <uuid>", "Batch UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--statuses <list>", "Statuses (comma-separated)")
-        .option("--parent-batch-uuid <uuid>", "Parent batch UUID")
-        .option("--parent-uuid <uuid>", "Parent run UUID")
-        .option("--parent-node-uuid <uuid>", "Parent node UUID")
-        .option("--is-group-parent", "Only group parents")
-        .option("--record-id <id>", "Record ID")
-        .option("--record-title <title>", "Record title")
-        .option("--record-title-or-id <value>", "Record title or ID")
-        .option("--is-finished", "Only finished runs")
-        .option("--executions-filter <json>", 'Executions filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"node","nodeSlug":"...","operator":"isRunning"}]}]})')
-        .option("--created-after <date>", "Created after date")
-        .option("--created-before <date>", "Created before date")
+        .description("Download outputs from a specific node in matching runs")
+        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID (string, required)")
+        .requiredOption("--output-node-slug <slug>", "Output node slug to download from (string, required)")
+        .option("--format <format>", "Export format: csv | json (default: csv)", "csv")
+        .option("--batch-uuid <uuid>", "Filter by batch UUID (string)")
+        .option("--release-uuid <uuid>", "Filter by release UUID (string)")
+        .option("--statuses <list>", "Filter by statuses (comma-separated: pending,running,finished,failed,cancelled)")
+        .option("--parent-batch-uuid <uuid>", "Filter by parent batch UUID (string)")
+        .option("--parent-uuid <uuid>", "Filter by parent run UUID (string)")
+        .option("--parent-node-uuid <uuid>", "Filter by parent node UUID (string)")
+        .option("--is-group-parent", "Only return group parents (boolean flag)")
+        .option("--record-id <id>", "Filter by record ID (string)")
+        .option("--record-title <title>", "Filter by record title (string)")
+        .option("--record-title-or-id <value>", "Filter by record title or ID (string)")
+        .option("--is-finished", "Only return finished runs (boolean flag)")
+        .option("--executions-filter <json>", "Filter by node executions (JSON object, same format as 'run list')")
+        .option("--created-after <date>", "Filter runs created after this date (ISO 8601 string)")
+        .option("--created-before <date>", "Filter runs created before this date (ISO 8601 string)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai orchestration run download-outputs --workflow-uuid 550e8400-... --output-node-slug my-output
+  $ cargo-ai orchestration run download-outputs --workflow-uuid 550e8400-... --output-node-slug my-output --format json
+  $ cargo-ai orchestration run download-outputs --workflow-uuid 550e8400-... --output-node-slug my-output --statuses finished --is-finished`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.run.downloadOutputs({
@@ -235,12 +256,12 @@ export function registerRunCommands(parent, getApi) {
     });
     run
         .command("get-metrics")
-        .description("Get run metrics")
-        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID")
-        .option("--release-uuid <uuid>", "Release UUID")
-        .option("--batch-uuid <uuid>", "Batch UUID")
-        .option("--created-after <date>", "Created after date")
-        .option("--created-before <date>", "Created before date")
+        .description("Get aggregated run metrics for a workflow")
+        .requiredOption("--workflow-uuid <uuid>", "Workflow UUID (string, required)")
+        .option("--release-uuid <uuid>", "Filter by release UUID (string)")
+        .option("--batch-uuid <uuid>", "Filter by batch UUID (string)")
+        .option("--created-after <date>", "Filter runs created after this date (ISO 8601 string)")
+        .option("--created-before <date>", "Filter runs created before this date (ISO 8601 string)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.run.getMetrics({

package/build/commands/segmentation/segment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segment.d.ts","sourceRoot":"","sources":["../../../src/commands/segmentation/segment.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,CAgON"}
+{"version":3,"file":"segment.d.ts","sourceRoot":"","sources":["../../../src/commands/segmentation/segment.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,CAgPN"}

package/build/commands/segmentation/segment.js

@@ -1,6 +1,8 @@
 import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerSegmentCommands(parent, getApi) {
-    const segment = parent.command("segment").description("Segment operations");
+    const segment = parent
+        .command("segment")
+        .description("Manage segments (list, get, create, update, remove, fetch, download)");
     segment
         .command("list")
         .description("List all segments")
@@ -20,12 +22,21 @@ export function registerSegmentCommands(parent, getApi) {
     segment
         .command("create")
         .description("Create a segment")
-        .requiredOption("--name <name>", "Segment name")
-        .requiredOption("--model-uuid <uuid>", "Model UUID")
-        .requiredOption("--filter <json>", 'Filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[]}]})')
-        .option("--sort <json>", 'Sort (JSON, e.g. {"slug":"created_at","order":"desc"})')
-        .option("--limit <n>", "Limit")
-        .option("--tracking-column-slugs <slugs>", "Tracking column slugs (comma-separated)")
+        .requiredOption("--name <name>", "Segment name (string, required)")
+        .requiredOption("--model-uuid <uuid>", "Model UUID (string, required)")
+        .requiredOption("--filter <json>", "Filter definition (JSON object, required)")
+        .option("--sort <json>", 'Sort definition (JSON object). Shape: {"slug": string, "order": "asc" | "desc"}')
+        .option("--limit <n>", "Max records in segment (integer)")
+        .option("--tracking-column-slugs <slugs>", "Column slugs to track changes on (comma-separated strings)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai segmentation segment create --name "Active Users" --model-uuid 550e8400-... \\
+      --filter '{"conjonction":"and","groups":[{"conjonction":"and","conditions":[]}]}'
+  $ cargo-ai segmentation segment create --name "Recent" --model-uuid 550e8400-... \\
+      --filter '{"conjonction":"and","groups":[]}' --sort '{"slug":"created_at","order":"desc"}' --limit 100
+
+Filter object shape:
+  { "conjonction": "and" | "or", "groups": [{ "conjonction": "and" | "or", "conditions": [...] }] }`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.segmentation.segment.create({
@@ -63,15 +74,15 @@ export function registerSegmentCommands(parent, getApi) {
     });
     segment
         .command("fetch")
-        .description("Fetch segment data")
-        .requiredOption("--model-uuid <uuid>", "Model UUID")
-        .requiredOption("--filter <json>", 'Filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[]}]})')
-        .option("--sort <json>", 'Sort (JSON, e.g. {"slug":"created_at","order":"desc"})')
-        .option("--limit <n>", "Limit")
-        .option("--fetching-limit <n>", "Fetching limit")
-        .option("--fetching-offset <n>", "Fetching offset")
-        .option("--enrich", "Enrich records")
-        .option("--sync", "Sync before fetching")
+        .description("Fetch segment records with optional enrichment")
+        .requiredOption("--model-uuid <uuid>", "Model UUID (string, required)")
+        .requiredOption("--filter <json>", "Filter definition (JSON object, required, same format as 'segment create')")
+        .option("--sort <json>", 'Sort definition (JSON object). Shape: {"slug": string, "order": "asc" | "desc"}')
+        .option("--limit <n>", "Max records in segment (integer)")
+        .option("--fetching-limit <n>", "Max records to fetch per page (integer)")
+        .option("--fetching-offset <n>", "Number of records to skip (integer)")
+        .option("--enrich", "Enrich records with additional data (boolean flag)")
+        .option("--sync", "Sync data sources before fetching (boolean flag)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.segmentation.segment.fetch({
@@ -103,12 +114,12 @@ export function registerSegmentCommands(parent, getApi) {
     segment
         .command("update")
         .description("Update a segment")
-        .requiredOption("--uuid <uuid>", "Segment UUID")
-        .option("--name <name>", "Segment name")
-        .option("--filter <json>", 'Filter (JSON, e.g. {"conjonction":"and","groups":[{"conjonction":"and","conditions":[]}]})')
-        .option("--sort <json>", 'Sort (JSON, e.g. {"slug":"created_at","order":"desc"})')
-        .option("--limit <n>", "Limit")
-        .option("--tracking-column-slugs <slugs>", "Tracking column slugs (comma-separated)")
+        .requiredOption("--uuid <uuid>", "Segment UUID (string, required)")
+        .option("--name <name>", "Segment name (string)")
+        .option("--filter <json>", "Filter definition (JSON object, same format as 'segment create')")
+        .option("--sort <json>", 'Sort definition (JSON object). Shape: {"slug": string, "order": "asc" | "desc"}')
+        .option("--limit <n>", "Max records in segment (integer)")
+        .option("--tracking-column-slugs <slugs>", "Column slugs to track changes on (comma-separated strings)")
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.segmentation.segment.update({

package/build/commands/storage/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/commands/storage/model.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,CAoMN"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/commands/storage/model.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,CA6MN"}

package/build/commands/storage/model.js

@@ -22,6 +22,7 @@ export function registerModelCommands(parent, getApi) {
         .description("Create a model")
         .requiredOption("--slug <slug>", "Model slug")
         .requiredOption("--name <name>", "Model name")
+        .option("--description <description>", "Model description")
         .requiredOption("--dataset-uuid <uuid>", "Dataset UUID")
         .requiredOption("--extractor-slug <slug>", "Extractor slug")
         .requiredOption("--config <json>", "Extractor configuration (JSON object)")
@@ -31,6 +32,7 @@ export function registerModelCommands(parent, getApi) {
         const result = await handleApiCall(() => api.storage.model.create({
             slug: opts.slug,
             name: opts.name,
+            description: opts.description,
             datasetUuid: opts.datasetUuid,
             extractorSlug: opts.extractorSlug,
             config: parseJson(opts.config, "--config"),
@@ -61,6 +63,7 @@ export function registerModelCommands(parent, getApi) {
         .description("Update a model")
         .requiredOption("--uuid <uuid>", "Model UUID")
         .option("--name <name>", "Model name")
+        .option("--description <description>", "Model description (or 'null' to clear)")
         .option("--extractor-slug <slug>", "Extractor slug")
         .option("--config <json>", "Extractor configuration (JSON object)")
         .option("--position <json>", 'Position (JSON, e.g. {"x":0,"y":0})')
@@ -71,6 +74,7 @@ export function registerModelCommands(parent, getApi) {
         const result = await handleApiCall(() => api.storage.model.update({
             uuid: opts.uuid,
             name: opts.name,
+            description: opts.description === "null" ? null : opts.description,
             extractorSlug: opts.extractorSlug,
             config: opts.config !== undefined
                 ? parseJson(opts.config, "--config")

package/build/commands/storage/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/commands/storage/record.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,CAiEN"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/commands/storage/record.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,CAiFN"}

package/build/commands/storage/record.js

@@ -5,9 +5,12 @@ export function registerRecordCommands(parent, getApi) {
         .description("Storage record operations");
     record
         .command("get")
-        .description("Get a storage record")
-        .requiredOption("--model-uuid <uuid>", "Model UUID")
-        .requiredOption("--id <id>", "Record ID")
+        .description("Get a storage record by ID")
+        .requiredOption("--model-uuid <uuid>", "Model UUID (string, required)")
+        .requiredOption("--id <id>", "Record ID (string, required)")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai storage record get --model-uuid 550e8400-... --id rec_abc123`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.storage.record.get({ modelUuid: opts.modelUuid, id: opts.id }));
@@ -16,11 +19,15 @@ export function registerRecordCommands(parent, getApi) {
     record
         .command("list")
         .description("List storage records")
-        .requiredOption("--model-uuid <uuid>", "Model UUID")
-        .option("--limit <n>", "Limit")
-        .option("--offset <n>", "Offset")
-        .option("--sort-kind <kind>", "Sort direction (asc|desc)")
-        .option("--sort-column-slug <slug>", "Sort column (_id|_title|_emitted_at)")
+        .requiredOption("--model-uuid <uuid>", "Model UUID (string, required)")
+        .option("--limit <n>", "Max results to return (integer)")
+        .option("--offset <n>", "Number of results to skip (integer)")
+        .option("--sort-kind <kind>", "Sort direction. Allowed values: asc, desc")
+        .option("--sort-column-slug <slug>", "Column to sort by. Allowed values: _id, _title, _emitted_at")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai storage record list --model-uuid 550e8400-...
+  $ cargo-ai storage record list --model-uuid 550e8400-... --limit 100 --sort-kind desc --sort-column-slug _emitted_at`)
         .action(async (opts) => {
         const api = getApi();
         const limit = opts.limit !== undefined ? parseInt(opts.limit, 10) : undefined;

package/build/commands/workspace/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/commands/workspace/user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAIxC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAmJ7E"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/commands/workspace/user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAIxC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CA0L7E"}

package/build/commands/workspace/user.js

@@ -1,7 +1,9 @@
 import { getConfig } from "../../config.js";
 import { handleApiCall, outputJson } from "../runHandler.js";
 export function registerUserCommands(parent, getApi) {
-    const user = parent.command("user").description("Workspace user operations");
+    const user = parent
+        .command("user")
+        .description("Manage workspace users and permissions");
     user
         .command("list")
         .description("List workspace users")
@@ -28,9 +30,12 @@ export function registerUserCommands(parent, getApi) {
     });
     user
         .command("create")
-        .description("Create a workspace user")
-        .requiredOption("--user-email <email>", "User email")
-        .requiredOption("--role-slug <slug>", "Role slug")
+        .description("Invite a user to the workspace")
+        .requiredOption("--user-email <email>", "User email address (string, required)")
+        .requiredOption("--role-slug <slug>", "Role slug to assign (string, required)")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai workspace user create --user-email alice@example.com --role-slug admin`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.workspaceManagement.user.create({
@@ -63,12 +68,16 @@ export function registerUserCommands(parent, getApi) {
     });
     user
         .command("upsert-permission")
-        .description("Upsert a user permission")
-        .option("--user-uuids <uuids>", "User UUIDs (comma-separated)")
-        .option("--emails <emails>", "User emails (comma-separated)")
-        .requiredOption("--action <action>", "Permission action")
-        .requiredOption("--resource-uuid <uuid>", "Resource UUID")
-        .requiredOption("--effect <effect>", "Permission effect (allow or deny)")
+        .description("Create or update a user permission")
+        .option("--user-uuids <uuids>", "Target user UUIDs (comma-separated strings). At least one of --user-uuids or --emails is required")
+        .option("--emails <emails>", "Target user emails (comma-separated strings). At least one of --user-uuids or --emails is required")
+        .requiredOption("--action <action>", "Permission action (string, required)")
+        .requiredOption("--resource-uuid <uuid>", "Resource UUID to grant/deny access to (string, required)")
+        .requiredOption("--effect <effect>", "Permission effect. Allowed values: allow, deny")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai workspace user upsert-permission --emails alice@example.com --action read --resource-uuid 550e8400-... --effect allow
+  $ cargo-ai workspace user upsert-permission --user-uuids uuid1,uuid2 --action write --resource-uuid 550e8400-... --effect deny`)
         .action(async (opts) => {
         if (opts.userUuids === undefined && opts.emails === undefined) {
             throw new Error("--user-uuids or --emails is required");
@@ -90,9 +99,9 @@ export function registerUserCommands(parent, getApi) {
     user
         .command("remove-permission")
         .description("Remove a user permission")
-        .requiredOption("--user-uuid <uuid>", "User UUID")
-        .requiredOption("--resource-uuid <uuid>", "Resource UUID")
-        .requiredOption("--effect <effect>", "Permission effect (allow or deny)")
+        .requiredOption("--user-uuid <uuid>", "User UUID (string, required)")
+        .requiredOption("--resource-uuid <uuid>", "Resource UUID (string, required)")
+        .requiredOption("--effect <effect>", "Permission effect to remove. Allowed values: allow, deny")
         .action(async (opts) => {
         const api = getApi();
         await handleApiCall(() => api.workspaceManagement.user.removePermission({

package/build/index.js

@@ -19,7 +19,20 @@ import { registerWorkspaceCommands } from "./commands/workspace/index.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 const program = new Command();
-program.name("cargo-ai").description("Cargo API CLI").version(version);
+program
+    .name("cargo-ai")
+    .description("Cargo API CLI")
+    .version(version)
+    .addHelpText("after", `
+Authentication:
+  Save credentials:   cargo-ai login --token <your-token>
+  Use env variables:  CARGO_API_TOKEN, CARGO_WORKSPACE_UUID, CARGO_BASE_URL
+  Check status:       cargo-ai whoami
+
+All commands output JSON to stdout. Errors exit with code 1.
+
+Run "cargo-ai <command> --help" for details on a specific command group.
+Run "cargo-ai <command> <subcommand> --help" for details on a subcommand.`);
 const getApi = () => createApi();
 registerAuthCommands(program, getApi);
 registerInitCommand(program, getApi);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "private": false,
   "description": "Command-line interface for the Cargo API",
   "engines": {
     "node": ">=22"
   },
   "volta": {
-    "node": "22.14.0"
+    "node": "22.22.2"
   },
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "commander": "^12.1.0",
-    "@cargo-ai/api": "^1.0.14"
+    "@cargo-ai/api": "^1.0.17"
   },
   "devDependencies": {
     "@cargo-ai/eslint-config": "*",