@cargo-ai/cli 1.0.44 → 1.0.45

package/build/commands/orchestration/action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAaxC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA+KN"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAaxC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA4LN"}

package/build/commands/orchestration/action.js

@@ -2,7 +2,17 @@ import { applyRecordsLimit, ExitCodes, failWith, handleApiCall, outputJson, pars
 export function registerActionCommands(parent, getApi) {
     const action = parent
         .command("action")
-        .description("Execute actions (single run or batch)");
+        .description("Execute actions (single run or batch)")
+        .addHelpText("after", `
+The default way to run a tool or connector action: no workflow, release, or node
+graph needed. Creates a run and consumes credits.
+
+  - 'config' inside --action must be empty ({}); inputs go in --data.
+  - The run is asynchronous: pass --wait-until-finished, or poll it with
+    'cargo-ai orchestration run get <uuid>'.
+
+To debug a node inside an existing workflow instead, use
+'cargo-ai orchestration node'.`);
     action
         .command("execute")
         .description("Execute a single action")

package/build/commands/orchestration/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAexC,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAkBN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAexC,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA0BN"}

package/build/commands/orchestration/index.js

@@ -14,7 +14,12 @@ import { registerWorkflowCommands } from "./workflow.js";
 export function registerOrchestrationCommands(parent, getApi) {
     const orchestration = parent
         .command("orchestration")
-        .description("Workflows, plays, runs, batches, tools, templates");
+        .description("Workflows, plays, runs, batches, tools, templates")
+        .addHelpText("after", `
+Running vs. debugging:
+  action  Run a tool or connector action — no workflow needed. The usual choice.
+  node    Debug one node of an existing workflow ('node compute' is free,
+          'node execute' really runs it and consumes credits).`);
     registerActionCommands(orchestration, getApi);
     registerWorkflowCommands(orchestration, getApi);
     registerPlayCommands(orchestration, getApi);

package/build/commands/orchestration/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/node.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,CAwG7E"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/node.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,CA8J7E"}

package/build/commands/orchestration/node.js

@@ -2,13 +2,33 @@ import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
 export function registerNodeCommands(parent, getApi) {
     const node = parent
         .command("node")
-        .description("Compute, validate, and execute workflow nodes");
+        .description("Debug a workflow one node at a time: compute a node's config, validate node definitions, execute a single node")
+        .addHelpText("after", `
+Use these commands to debug one node of an existing workflow release. To just
+run a tool or connector action, no workflow needed, use instead:
+  $ cargo-ai orchestration action execute --action '<json>' --data '<json>'
+
+'compute' and 'validate' are free and run nothing. 'execute' is not a dry run:
+it performs the node's real action and consumes credits.
+
+Debugging loop:
+  $ cargo-ai orchestration span list --run-uuid <uuid> --execution-started-after <iso-date>
+  $ cargo-ai orchestration release get-deployed --workflow-uuid <uuid>
+  $ cargo-ai orchestration node compute --node '<json>' --context '<json>'
+  $ cargo-ai orchestration node execute --workflow-uuid <uuid> --release-uuid <uuid> --node '<json>' --computed-config '<json>' --context '<json>'`);
     node
         .command("compute")
         .description("Compute a node's configuration from its definition and context")
         .requiredOption("--node <json>", "Node definition (JSON object, required)")
         .requiredOption("--context <json>", "Execution context (JSON object, required)")
         .option("--group-context <json>", "Group context for grouped nodes (JSON object)")
+        .addHelpText("after", `
+Free, runs nothing: resolves the node's template expressions against --context,
+so you can see a node's inputs before spending credits on it. Returns
+{"computedConfig":{...}} — pass that inner object to 'node execute'.
+
+Examples:
+  $ cargo-ai orchestration node compute --node '{"uuid":"...","slug":"enrich","kind":"connector","integrationSlug":"clearbit","actionSlug":"company_enrich","connectorUuid":"...","config":{"domain":{"kind":"templateExpression","expression":"{{nodes.start.domain}}","instructTo":"none","fromRecipe":false}}}' --context '{"nodes":{"start":{"domain":"acme.com"}}}'`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.node.compute({
@@ -24,6 +44,13 @@ export function registerNodeCommands(parent, getApi) {
         .command("validate")
         .description("Validate node definitions for correctness")
         .requiredOption("--nodes <json>", "Node definitions to validate (JSON array, required)")
+        .addHelpText("after", `
+Free, runs nothing: checks that a node graph is well-formed. Takes the whole
+graph as a JSON array, not a single node. Returns {"outcome":"valid"} or
+{"outcome":"notValid","invalidNodes":[...]}.
+
+Examples:
+  $ cargo-ai orchestration node validate --nodes '[{"uuid":"00000000-0001-0000-0000-000000000000","slug":"start","kind":"native","actionSlug":"start","config":{},"childrenUuids":[],"fallbackOnFailure":false,"position":{"x":0,"y":0}}]'`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.node.validate({
@@ -40,6 +67,19 @@ export function registerNodeCommands(parent, getApi) {
         .requiredOption("--computed-config <json>", "Computed configuration from 'node compute' (JSON object, required)")
         .requiredOption("--context <json>", "Execution context (JSON object, required)")
         .option("--group-context <json>", "Group context for grouped nodes (JSON object)")
+        .addHelpText("after", `
+Not a dry run: performs the node's real action and consumes credits. The node
+must belong to the given release — to run an arbitrary action with no workflow,
+use 'cargo-ai orchestration action execute' instead.
+
+Get --workflow-uuid, --release-uuid and --node from 'release get-deployed', and
+--computed-config from the 'computedConfig' of 'node compute'.
+
+Returns {"status":"success","data":{...},"creditsUsedCount":N}, or
+{"status":"pending","runUuid":"..."} — poll that with 'orchestration run get'.
+
+Examples:
+  $ cargo-ai orchestration node execute --workflow-uuid <uuid> --release-uuid <uuid> --node '<json>' --computed-config '{"domain":"acme.com"}' --context '{"nodes":{"start":{"domain":"acme.com"}}}'`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.node.execute({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.44",
+  "version": "1.0.45",
   "private": false,
   "license": "UNLICENSED",
   "description": "Command-line interface for the Cargo API",