@soat/cli 0.23.0 → 0.24.0

package/dist/index.mjs

@@ -1,5 +1,4 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { createHmac, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,13 +10,20 @@ import { program } from "commander";
 import * as fs from "node:fs";
 import { load } from "js-yaml";
 import * as os from "node:os";
+import { createHmac, timingSafeEqual } from "node:crypto";
 
 //#region package.json
-var version = "0.23.0";
+var version = "0.24.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
 var FORMATION_COMMANDS = ["validate-formation", "plan-formation", "create-formation", "update-formation"];
+/**
+* The two commands that *deploy*. `validate-formation` and `plan-formation`
+* report on a template without touching a resource, so their outcome is the
+* payload, not an exit code.
+*/
+var DEPLOY_COMMANDS = ["create-formation", "update-formation"];
 var TEMPLATE_PATH_FLAG = "template-path";
 var TEMPLATE_FILE_FLAG = "template-file";
 var ENV_FILE_FLAG = "env-file";
@@ -121,9 +127,45 @@ var resolveParameterPair = args => {
     })
   };
 };
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var readString = value => {
+  return typeof value === "string" && value ? value : void 0;
+};
+/** The reason line, from the response's `error` bag when it carries one. */
+var describeDeployReason = args => {
+  const reason = readString(args.error?.message);
+  if (!reason) return `No reason was reported on the response; run \`soat list-formation-events --formation-id ${args.formationId ?? "<id>"}\` for the operation history.`;
+  return `${readString(args.error?.code) ?? "UNKNOWN"}: ${reason}`;
+};
+/**
+* A deploy whose reconciliation failed, rendered for stderr.
+*
+* The server answers 2xx here on purpose — the operation ran, and partial
+* failure is modelled on the resource — so the body's `status` is the only
+* signal that anything went wrong. Turning it into a non-zero exit is what
+* stops `&&` chains from reporting a deploy that deployed nothing (#1028).
+*/
+var describeFailedDeploy = args => {
+  const {
+    commandName,
+    data
+  } = args;
+  if (!DEPLOY_COMMANDS.includes(commandName)) return null;
+  if (!isRecord(data) || data.status !== "failed") return null;
+  const error = isRecord(data.error) ? data.error : void 0;
+  const meta = isRecord(error?.meta) ? error.meta : void 0;
+  const logicalId = readString(meta?.logical_id);
+  return `${commandName}: the deploy failed${logicalId ? ` at resource '${logicalId}'` : ""} — the formation is 'failed'. ${describeDeployReason({
+    error,
+    formationId: readString(data.id)
+  })}`;
+};
 var formationsWrapper = {
   id: "formations-wrapper",
   commands: FORMATION_COMMANDS,
+  failureMessage: describeFailedDeploy,
   helpFlags: [{
     name: "template-path",
     description: "Path to template file (JSON or YAML). Alias: --template-file",
@@ -332,6 +374,18 @@ var applyWrapperForCommand = args => {
     }
   });
 };
+/**
+* What to report for a 2xx payload whose own body says the operation failed,
+* or null when there is nothing wrong with it. Drives the CLI's exit code.
+*/
+var resolveFailureMessage = args => {
+  return resolveWrapperForCommand({
+    commandName: args.commandName
+  })?.failureMessage?.({
+    commandName: args.commandName,
+    data: args.data
+  }) ?? null;
+};
 var getWrapperHelpFlags = commandName => {
   return WRAPPERS.find(w => {
     return w.commands.includes(commandName);
@@ -1179,7 +1233,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "trace_id",
-      "description": "Optional trace ID to group generations",
+      "description": "Optional trace ID to group generations. Each generation appends its own steps to the trace's steps object, and `step_count` covers them all.",
       "required": false,
       "type": "string",
       "in": "body"
@@ -1590,7 +1644,7 @@ var routes = {
   "list-ai-provider-models": {
     serviceClass: "AIProviders",
     operationId: "listAiProviderModels",
-    description: "Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry. Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time. Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`.",
+    description: "Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry. Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time. Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`. Listing resolves credentials the same way generation does, so a record that can generate can list. The API-key types (`openai`, `groq`, `xai`, `gateway`, `custom`, `anthropic`, `google`) use the record's linked secret and cannot list without one. `bedrock` and `vertex` use the linked secret when there is one — IAM keys or a Bedrock API key, a Google service-account key — and otherwise fall back to the server environment (the AWS default credential chain, Google Application Default Credentials), so a record with no `secret_id` can still list. A Vertex record needs no `config.project` when its secret is a service-account key, since the key file names its own project. A Vertex record in express mode (API key) cannot list at all: express mode is a global, project-less endpoint and the publisher-model catalogue is per-project, so it returns `400 MODEL_LISTING_UNSUPPORTED`.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     httpMethod: "get",
     pathParams: ["ai_provider_id"],
@@ -1644,7 +1698,7 @@ var routes = {
   "list-api-keys": {
     serviceClass: "APIKeys",
     operationId: "listApiKeys",
-    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - API key: returns only API keys scoped to the key's project.",
+    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "get",
     pathParams: [],
@@ -1666,7 +1720,7 @@ var routes = {
   "create-api-key": {
     serviceClass: "APIKeys",
     operationId: "createApiKey",
-    description: "Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped).",
+    description: "Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "post",
     pathParams: [],
@@ -1694,7 +1748,7 @@ var routes = {
   "get-api-key": {
     serviceClass: "APIKeys",
     operationId: "getApiKey",
-    description: "Returns details of an API key. Only the owner or an admin can access it.",
+    description: "Returns details of an API key. Only the owner or an admin can access it, and a project-scoped credential can only reach keys in its own project.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "get",
     pathParams: ["api_key_id"],
@@ -1710,7 +1764,7 @@ var routes = {
   "update-api-key": {
     serviceClass: "APIKeys",
     operationId: "updateApiKey",
-    description: "Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it.",
+    description: "Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "put",
     pathParams: ["api_key_id"],
@@ -1744,7 +1798,7 @@ var routes = {
   "delete-api-key": {
     serviceClass: "APIKeys",
     operationId: "deleteApiKey",
-    description: "Deletes an API key. Only the owner or an admin can delete it.",
+    description: "Deletes an API key. Only the owner or an admin can delete it, and a project-scoped credential can only delete keys in its own project.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "delete",
     pathParams: ["api_key_id"],
@@ -3996,7 +4050,7 @@ var routes = {
   "create-formation": {
     serviceClass: "Formations",
     operationId: "createFormation",
-    description: "Validates the template, creates the formation record, then provisions all declared resources in dependency order.",
+    description: "Validates the template, creates the formation record, then provisions all declared resources in dependency order. A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `201` and `status: \"failed\"`, and `error` explains why (the resources created before the failure are rolled back). Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `soat` CLI exits non-zero on that body so `create-formation && …` does not lie.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "post",
     pathParams: [],
@@ -4052,7 +4106,7 @@ var routes = {
   "update-formation": {
     serviceClass: "Formations",
     operationId: "updateFormation",
-    description: "Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.",
+    description: "Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state. A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: \"failed\"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `soat` CLI exits non-zero on that body so `update-formation && …` does not lie.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "put",
     pathParams: ["formation_id"],
@@ -4227,6 +4281,22 @@ var routes = {
       "in": "path"
     }]
   },
+  "get-generation-transcript": {
+    serviceClass: "Generations",
+    operationId: "getGenerationTranscript",
+    description: "Returns one generation's turn read back as an ordered sequence of steps: what it was asked, each model step with its tool calls and results, and how it ended. The transcript is assembled at read time from the generation record and the trace's steps object; nothing is stored, so it cannot outlive the content it projects. Requires `traces:GetTrace` in addition to `generations:GetGeneration`, because the response merges content from both resources. A generation whose content is unavailable — never written under zero-retention, or cleared by a purge — returns `200` with the skeleton rather than an error: `input` and `output` are null, `steps` is empty, and the `content_redacted_*` fields say which happened. `content_redacted_by_principal_id` is `zero_retention` when the content was never stored, and the purging principal's ID when it was erased later. A generation that is still running returns the same shape with an empty `steps`; `status` disambiguates the two.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
+    httpMethod: "get",
+    pathParams: ["generation_id"],
+    queryParams: [],
+    flags: [{
+      "name": "generation_id",
+      "description": "Public ID of the generation",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-guardrails": {
     serviceClass: "Guardrails",
     operationId: "listGuardrails",
@@ -4749,7 +4819,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "min_score",
-      "description": "Minimum similarity score (0–1). Results with lower scores are excluded. Only applies when `query` is provided.",
+      "description": "Minimum `score` a result must reach to be returned. Filters on the implementation-defined `score`, not on `similarity_score`, so the cutoff follows the ranking. Only applies when `query` is provided. Because the scale behind `score` is not part of the contract, treat a tuned value as tied to the deployment rather than portable.",
       "required": false,
       "type": "number",
       "in": "body"
@@ -4926,7 +4996,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["memory_id", "limit", "offset"],
+    queryParams: ["memory_id", "limit", "offset", "include_invalidated"],
     flags: [{
       "name": "memory_id",
       "description": "Memory container to list entries from (mem_...)",
@@ -4945,6 +5015,12 @@ var routes = {
       "required": false,
       "type": "integer",
       "in": "query"
+    }, {
+      "name": "include_invalidated",
+      "description": "Include invalidated (superseded) entries. They are excluded by default; set this to audit the supersede history.",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
     }]
   },
   "create-memory-entry": {
@@ -6475,6 +6551,80 @@ var routes = {
       "in": "body"
     }]
   },
+  "fork-session": {
+    serviceClass: "Sessions",
+    operationId: "forkSession",
+    description: "Branches a new session from a point in this session's history: same context, different continuation. The fork gets its own conversation whose messages **reference the same documents** as the parent rather than copying them, so there is one stored copy of the content and a retention purge erases it from both. Recorded tool results ride along on those messages and are **replayed** as model input on the fork's next turn — forking never re-invokes a tool, so exploring a \"what if\" cannot send an email or charge a card a second time. The consequence to accept is that a forked turn sees the tool data as it was, not as it is now. The fork is created **inert**: `auto_generate` is false and no generation is triggered. Drive it with the normal message and generate endpoints. The fork has no actor — attach one only if the branch is meant to be driven by the same end user, since `single_session_per_actor` agents allow one open session per actor.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
+    httpMethod: "post",
+    pathParams: ["session_id"],
+    queryParams: [],
+    flags: [{
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "fork_at_position",
+      "description": "The parent conversation `position` to branch after. Messages at positions 0..N are carried into the fork. Omit it to branch at the tip (the whole history).\n",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "agent_id",
+      "description": "Agent the fork runs against. Defaults to the parent session's agent; overriding it is the point of forking — same context, a different agent or agent version. Must belong to the same project as the session being forked.\n",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Optional name for the forked session",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Optional tags for the forked session",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "tool_context",
+      "description": "Overrides the parent's `tool_context` on the fork. Omit it and the fork inherits the parent's, so the branch is faithful to the run it came from.\n",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
+  },
+  "list-session-forks": {
+    serviceClass: "Sessions",
+    operationId: "listSessionForks",
+    description: "Returns the sessions forked directly from this one. One level of lineage: a fork of a fork is listed under its own parent.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
+    httpMethod: "get",
+    pathParams: ["session_id"],
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
   "get-session-tags": {
     serviceClass: "Sessions",
     operationId: "getSessionTags",
@@ -8019,6 +8169,22 @@ var routes = {
       "in": "path"
     }]
   },
+  "redeliver-webhook-delivery": {
+    serviceClass: "Webhooks",
+    operationId: "redeliverWebhookDelivery",
+    description: "Queues the stored payload of an existing delivery to be sent again. A new delivery record is created rather than the original being reset, so the original attempt stays in the history. The send happens in the background: poll the returned delivery to observe its outcome.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
+    httpMethod: "post",
+    pathParams: ["delivery_id"],
+    queryParams: [],
+    flags: [{
+      "name": "delivery_id",
+      "description": "Delivery to send again (wh_deliv_...)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "get-webhook-secret": {
     serviceClass: "Webhooks",
     operationId: "getWebhookSecret",
@@ -8390,6 +8556,76 @@ var findUnknownFlags = args => {
   }), `Run "soat ${args.commandName} --help" to see the flags this command accepts.`];
 };
 
+//#endregion
+//#region src/webhookSignature.ts
+var digestMatches = args => {
+  const expectedBuffer = Buffer.from(args.expected, "utf8");
+  const actualBuffer = Buffer.from(args.actual, "utf8");
+  if (expectedBuffer.length !== actualBuffer.length) return false;
+  return timingSafeEqual(expectedBuffer, actualBuffer);
+};
+/** Deprecated scheme: `sha256=<hex>` over the bare body. */
+var verifyLegacySignature = args => {
+  const expected = createHmac("sha256", args.secret).update(args.payload).digest("hex");
+  return digestMatches({
+    expected,
+    actual: args.header
+  });
+};
+/**
+* Timestamped scheme: `t=<unix>,v1=<hex>` over `<t>.<body>`.
+*
+* The timestamp must be present, but its age is deliberately not enforced here:
+* this is a local debugging listener, and rejecting a delivery over clock skew
+* would read as a signing bug. A real subscriber should enforce a tolerance
+* window — the webhooks module docs show one.
+*/
+var verifyTimestampedSignature = args => {
+  const elements = new Map(args.header.split(",").map(part => {
+    const separator = part.indexOf("=");
+    return [part.slice(0, separator).trim(), part.slice(separator + 1)];
+  }));
+  const timestamp = elements.get("t");
+  const digest = elements.get("v1");
+  if (!timestamp || !digest) return false;
+  const expected = createHmac("sha256", args.secret).update(`${timestamp}.${args.payload}`).digest("hex");
+  return digestMatches({
+    expected,
+    actual: digest
+  });
+};
+var headerValue = value => {
+  if (Array.isArray(value)) return value[0] ?? "";
+  return value ?? "";
+};
+/**
+* Picks the scheme a delivery used and verifies it, when a secret is supplied.
+*/
+var inspectDeliverySignature = args => {
+  const timestamped = headerValue(args.headers["x-soat-signature-v2"]);
+  const legacy = headerValue(args.headers["x-soat-signature"]);
+  const scheme = timestamped ? "v2" : "v1";
+  const signature = timestamped || legacy;
+  if (!args.secret) return {
+    signature,
+    scheme,
+    valid: null
+  };
+  return {
+    signature,
+    scheme,
+    valid: scheme === "v2" ? verifyTimestampedSignature({
+      secret: args.secret,
+      payload: args.payload,
+      header: timestamped
+    }) : verifyLegacySignature({
+      secret: args.secret,
+      payload: args.payload,
+      header: legacy
+    })
+  };
+};
+
 //#endregion
 //#region src/index.ts
 /**
@@ -8454,14 +8690,7 @@ var matchesFilter = (eventType, filter) => {
     return eventType === pattern;
   });
 };
-var verifySignature = (secret, payload, signatureHeader) => {
-  const expected = createHmac("sha256", secret).update(payload).digest("hex");
-  const expectedBuffer = Buffer.from(expected, "utf8");
-  const actualBuffer = Buffer.from(signatureHeader, "utf8");
-  if (expectedBuffer.length !== actualBuffer.length) return false;
-  return timingSafeEqual(expectedBuffer, actualBuffer);
-};
-program.command("listen").description("Start a local webhook listener for testing deliveries").option("--port <number>", "port to listen on", "8787").option("--path <path>", "request path to accept", "/webhook").option("--secret <secret>", "verify X-Soat-Signature with this webhook secret").option("--filter <pattern>", "filter event type(s), supports prefix wildcard and comma separation (e.g. sessions.generation.*,files.*)").option("--json", "print one JSON object per line").action(opts => {
+program.command("listen").description("Start a local webhook listener for testing deliveries").option("--port <number>", "port to listen on", "8787").option("--path <path>", "request path to accept", "/webhook").option("--secret <secret>", "verify the delivery signature with this webhook secret").option("--filter <pattern>", "filter event type(s), supports prefix wildcard and comma separation (e.g. sessions.generation.*,files.*)").option("--json", "print one JSON object per line").action(opts => {
   const port = Number(opts.port);
   const path = opts.path;
   const secret = opts.secret;
@@ -8489,7 +8718,6 @@ program.command("listen").description("Start a local webhook listener for testin
       const rawBody = Buffer.concat(chunks).toString("utf8");
       const eventType = String(req.headers["x-soat-event"] ?? "unknown");
       const deliveryId = String(req.headers["x-soat-delivery"] ?? "unknown");
-      const signature = String(req.headers["x-soat-signature"] ?? "");
       if (filter && !matchesFilter(eventType, filter)) {
         res.writeHead(200, {
           "Content-Type": "application/json"
@@ -8504,24 +8732,28 @@ program.command("listen").description("Start a local webhook listener for testin
       try {
         parsedPayload = JSON.parse(rawBody);
       } catch {}
-      let isSignatureValid = null;
-      if (secret) isSignatureValid = verifySignature(secret, rawBody, signature);
+      const inspected = inspectDeliverySignature({
+        secret,
+        payload: rawBody,
+        headers: req.headers
+      });
       const record = {
         timestamp: (/* @__PURE__ */new Date()).toISOString(),
         event_type: eventType,
         delivery_id: deliveryId,
-        signature,
-        signature_valid: isSignatureValid,
+        signature: inspected.signature,
+        signature_scheme: inspected.scheme,
+        signature_valid: inspected.valid,
         payload: parsedPayload
       };
       if (asJson) console.log(JSON.stringify(record));else {
         console.log("--- webhook received ---");
         console.log("event_type:", eventType);
         console.log("delivery_id:", deliveryId);
-        if (secret) console.log("signature_valid:", isSignatureValid);
+        if (secret) console.log("signature_valid:", inspected.valid);
         console.log("payload:", JSON.stringify(parsedPayload, null, 2));
       }
-      const responseStatus = secret && isSignatureValid === false ? 401 : 200;
+      const responseStatus = secret && inspected.valid === false ? 401 : 200;
       res.writeHead(responseStatus, {
         "Content-Type": "application/json"
       });
@@ -8529,7 +8761,7 @@ program.command("listen").description("Start a local webhook listener for testin
         ok: responseStatus === 200,
         event_type: eventType,
         delivery_id: deliveryId,
-        signature_valid: isSignatureValid
+        signature_valid: inspected.valid
       }));
     });
   });
@@ -8667,6 +8899,14 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
     process.exit(1);
   }
   console.log(await formatResultData(result.data));
+  const failure = resolveFailureMessage({
+    commandName,
+    data: result.data
+  });
+  if (failure) {
+    console.error(failure);
+    process.exit(1);
+  }
 });
 var runCli = async args => {
   const previousArgv = process.argv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "type": "module",
   "dependencies": {
     "@inquirer/input": "^5.1.2",
@@ -8,7 +8,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.23.0"
+    "@soat/sdk": "0.24.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",