retell-cli 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to the Retell AI CLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] - 2026-04-30
+
+### Added
+
+- `calls stop <call_id>` — stop an ongoing call via `client.call.stop`.
+- `exports list` — list export requests with `--limit`, `--pagination-key`, `--sort-order`, and `--fields`.
+- `playground complete <agent_id>` — run stateless playground completions with JSON or `@path` messages, optional dynamic variables, tool mocks, state/node/component context, agent version, and field filtering.
+
+### Changed
+
+- Bumped the minimum Node.js engine from `>=18.0.0` to `>=18.10.0` to match the current Retell SDK requirement.
+- Bumped `retell-sdk` from `^5.12.0` to `^5.18.0`.
+- Migrated test API helpers from direct `fetch` calls to SDK-backed `client.tests.*` wrappers while preserving existing command output shapes.
+
+### Fixed
+
+- `exports list --limit` now rejects non-positive and fractional values before calling the SDK.
+- `playground complete --fields` now ignores empty field tokens and returns the full response when no valid field paths remain.
+
 ## [1.6.0] - 2026-04-16
 
 Bulk addition of CLI surface for Retell SDK resources that were previously unwrapped or partially wrapped. Bumped `retell-sdk` dependency to `^5.12.0`.

package/dist/index.js

@@ -49,6 +49,7 @@ var ConfigError = class extends Error {
     this.code = code;
     this.name = "ConfigError";
   }
+  code;
 };
 function getConfigPath() {
   return (0, import_path.join)(process.cwd(), CONFIG_FILE_NAME);
@@ -2915,105 +2916,62 @@ async function importToolsCommand(agentId, options) {
 }
 
 // src/services/test-api.ts
-var BASE_URL = "https://api.retellai.com";
-async function apiRequest(method, path, body) {
-  const config = getConfig();
-  const response = await fetch(`${BASE_URL}${path}`, {
-    method,
-    headers: {
-      Authorization: `Bearer ${config.apiKey}`,
-      "Content-Type": "application/json"
-    },
-    body: body ? JSON.stringify(body) : void 0
-  });
-  if (!response.ok) {
-    const errorBody = await response.text();
-    let errorMessage = `API error: ${response.status} ${response.statusText}`;
-    try {
-      const errorJson = JSON.parse(errorBody);
-      if (errorJson.message) {
-        errorMessage = errorJson.message;
-      } else if (errorJson.error) {
-        errorMessage = errorJson.error;
-      }
-    } catch {
-      if (errorBody) {
-        errorMessage = errorBody;
-      }
-    }
-    throw new Error(errorMessage);
-  }
-  const text = await response.text();
-  if (!text) {
-    return {};
-  }
-  return JSON.parse(text);
-}
 async function listTestCaseDefinitions(responseEngine) {
-  const params = new URLSearchParams();
-  if (responseEngine.type === "retell-llm") {
-    params.set("type", "retell-llm");
-    params.set("llm_id", responseEngine.llm_id);
-  } else {
-    params.set("type", "conversation-flow");
-    params.set("conversation_flow_id", responseEngine.conversation_flow_id);
-  }
-  return apiRequest(
-    "GET",
-    `/list-test-case-definitions?${params.toString()}`
+  const client = getRetellClient();
+  return await client.tests.listTestCaseDefinitions(
+    responseEngine
   );
 }
 async function getTestCaseDefinition(testCaseDefinitionId) {
-  return apiRequest(
-    "GET",
-    `/get-test-case-definition/${testCaseDefinitionId}`
+  const client = getRetellClient();
+  return await client.tests.getTestCaseDefinition(
+    testCaseDefinitionId
   );
 }
 async function createTestCaseDefinition(params) {
-  return apiRequest(
-    "POST",
-    "/create-test-case-definition",
+  const client = getRetellClient();
+  return await client.tests.createTestCaseDefinition(
     params
   );
 }
 async function updateTestCaseDefinition(testCaseDefinitionId, params) {
-  return apiRequest(
-    "PUT",
-    `/update-test-case-definition/${testCaseDefinitionId}`,
+  const client = getRetellClient();
+  return await client.tests.updateTestCaseDefinition(
+    testCaseDefinitionId,
     params
   );
 }
 async function deleteTestCaseDefinition(testCaseDefinitionId) {
-  await apiRequest(
-    "DELETE",
-    `/delete-test-case-definition/${testCaseDefinitionId}`
-  );
+  const client = getRetellClient();
+  await client.tests.deleteTestCaseDefinition(testCaseDefinitionId);
 }
 async function listBatchTests(responseEngine) {
-  const params = new URLSearchParams();
-  if (responseEngine.type === "retell-llm") {
-    params.set("type", "retell-llm");
-    params.set("llm_id", responseEngine.llm_id);
-  } else {
-    params.set("type", "conversation-flow");
-    params.set("conversation_flow_id", responseEngine.conversation_flow_id);
-  }
-  return apiRequest(
-    "GET",
-    `/list-batch-tests?${params.toString()}`
+  const client = getRetellClient();
+  return await client.tests.listBatchTests(
+    responseEngine
   );
 }
 async function getBatchTest(batchJobId) {
-  return apiRequest("GET", `/get-batch-test/${batchJobId}`);
+  const client = getRetellClient();
+  return await client.tests.getBatchTest(
+    batchJobId
+  );
 }
 async function createBatchTest(params) {
-  return apiRequest("POST", "/create-batch-test", params);
+  const client = getRetellClient();
+  return await client.tests.createBatchTest(
+    params
+  );
 }
 async function listTestRuns(batchJobId) {
-  return apiRequest("GET", `/list-test-runs/${batchJobId}`);
+  const client = getRetellClient();
+  return await client.tests.listTestRuns(
+    batchJobId
+  );
 }
 async function getTestRun(testRunId) {
-  return apiRequest("GET", `/get-test-run/${testRunId}`);
+  const client = getRetellClient();
+  return await client.tests.getTestRun(testRunId);
 }
 
 // src/commands/tests/cases/list.ts
@@ -4439,6 +4397,21 @@ async function deleteCallCommand(callId) {
   }
 }
 
+// src/commands/calls/stop.ts
+async function stopCallCommand(callId) {
+  try {
+    const client = getRetellClient();
+    await client.call.stop(callId);
+    outputJson({
+      message: "Call stopped successfully",
+      call_id: callId,
+      operation: "stop"
+    });
+  } catch (error) {
+    handleSdkError(error);
+  }
+}
+
 // src/commands/batch-calls/create.ts
 async function createBatchCallCommand(options) {
   try {
@@ -4487,6 +4460,44 @@ function throwValidation9(message) {
   throw err;
 }
 
+// src/commands/export-requests/list.ts
+var SORT_ORDERS = ["ascending", "descending"];
+async function listExportRequestsCommand(options = {}) {
+  try {
+    const query = {};
+    if (options.limit !== void 0) {
+      const limit = parseNumericFlag(options.limit, "--limit");
+      if (!Number.isInteger(limit) || limit < 1) {
+        throwValidation10("--limit must be a positive integer");
+      }
+      query.limit = limit;
+    }
+    if (options.paginationKey) query.pagination_key = options.paginationKey;
+    if (options.sortOrder !== void 0) {
+      if (!SORT_ORDERS.includes(options.sortOrder)) {
+        throwValidation10(
+          `--sort-order must be one of: ${SORT_ORDERS.join(", ")}`
+        );
+      }
+      query.sort_order = options.sortOrder;
+    }
+    const client = getRetellClient();
+    const exportRequests = await client.exportRequest.list(query);
+    const output = options.fields ? filterFields(
+      exportRequests,
+      options.fields.split(",").map((f) => f.trim())
+    ) : exportRequests;
+    outputJson(output);
+  } catch (error) {
+    handleSdkError(error);
+  }
+}
+function throwValidation10(message) {
+  const err = new Error(message);
+  err.name = "ValidationError";
+  throw err;
+}
+
 // src/commands/llms/list.ts
 async function listLlmsCommand(options = {}) {
   try {
@@ -4545,7 +4556,7 @@ async function createLlmCommand(options = {}) {
         options.beginMessage !== void 0 && "--begin-message"
       ].filter(Boolean);
       if (simpleFlags.length > 0) {
-        throwValidation10(
+        throwValidation11(
           `--file is mutually exclusive with ${simpleFlags.join(", ")}. Put all fields in the JSON body.`
         );
       }
@@ -4563,7 +4574,7 @@ async function createLlmCommand(options = {}) {
         params.s2s_model = options.s2sModel;
       if (options.startSpeaker) {
         if (!["user", "agent"].includes(options.startSpeaker))
-          throwValidation10("--start-speaker must be 'user' or 'agent'");
+          throwValidation11("--start-speaker must be 'user' or 'agent'");
         params.start_speaker = options.startSpeaker;
       }
       if (options.beginMessage !== void 0)
@@ -4580,7 +4591,7 @@ async function createLlmCommand(options = {}) {
     handleSdkError(error);
   }
 }
-function throwValidation10(message) {
+function throwValidation11(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -4668,7 +4679,7 @@ var VALID_PROVIDERS2 = [
 async function addVoiceResourceCommand(options) {
   try {
     if (options.voiceProvider && !VALID_PROVIDERS2.includes(options.voiceProvider)) {
-      throwValidation11(
+      throwValidation12(
         `--voice-provider must be one of: ${VALID_PROVIDERS2.join(", ")}`
       );
     }
@@ -4693,7 +4704,7 @@ async function addVoiceResourceCommand(options) {
     handleSdkError(error);
   }
 }
-function throwValidation11(message) {
+function throwValidation12(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -4711,17 +4722,17 @@ var VALID_PROVIDERS3 = [
 async function cloneVoiceCommand(options) {
   try {
     if (!VALID_PROVIDERS3.includes(options.voiceProvider)) {
-      throwValidation12(
+      throwValidation13(
         `--voice-provider must be one of: ${VALID_PROVIDERS3.join(", ")}`
       );
     }
     const files = options.file ?? [];
     if (files.length === 0) {
-      throwValidation12("at least one --file is required");
+      throwValidation13("at least one --file is required");
     }
     for (const path of files) {
       if (!(0, import_fs18.existsSync)(path)) {
-        throwValidation12(`--file: not found: ${path}`);
+        throwValidation13(`--file: not found: ${path}`);
       }
     }
     const params = {
@@ -4740,7 +4751,7 @@ async function cloneVoiceCommand(options) {
     handleSdkError(error);
   }
 }
-function throwValidation12(message) {
+function throwValidation13(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -4756,7 +4767,7 @@ var VALID_PROVIDERS4 = [
 async function searchVoicesCommand(options) {
   try {
     if (options.voiceProvider && !VALID_PROVIDERS4.includes(options.voiceProvider)) {
-      throwValidation13(
+      throwValidation14(
         `--voice-provider must be one of: ${VALID_PROVIDERS4.join(", ")}`
       );
     }
@@ -4777,7 +4788,7 @@ async function searchVoicesCommand(options) {
     handleSdkError(error);
   }
 }
-function throwValidation13(message) {
+function throwValidation14(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -4837,7 +4848,7 @@ async function listChatsCommand(options = {}) {
     if (options.paginationKey) query.pagination_key = options.paginationKey;
     if (options.sortOrder) {
       if (!["ascending", "descending"].includes(options.sortOrder))
-        throwValidation14("--sort-order must be 'ascending' or 'descending'");
+        throwValidation15("--sort-order must be 'ascending' or 'descending'");
       query.sort_order = options.sortOrder;
     }
     const client = getRetellClient();
@@ -4851,7 +4862,7 @@ async function listChatsCommand(options = {}) {
     handleSdkError(error);
   }
 }
-function throwValidation14(message) {
+function throwValidation15(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -4872,14 +4883,14 @@ async function updateChatCommand(chatId, options) {
       params.override_dynamic_variables = dv;
     if (options.dataStorageSetting) {
       if (!DATA_STORAGE_SETTINGS2.includes(options.dataStorageSetting)) {
-        throwValidation15(
+        throwValidation16(
           `--data-storage-setting must be one of: ${DATA_STORAGE_SETTINGS2.join(", ")}`
         );
       }
       params.data_storage_setting = options.dataStorageSetting;
     }
     if (Object.keys(params).length === 0) {
-      throwValidation15(
+      throwValidation16(
         "No mutation flags provided. Pass at least one of --metadata, --custom-attributes, --dynamic-variables, --data-storage-setting."
       );
     }
@@ -4894,7 +4905,7 @@ async function updateChatCommand(chatId, options) {
     handleSdkError(error);
   }
 }
-function throwValidation15(message) {
+function throwValidation16(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -4977,7 +4988,7 @@ async function createChatAgentCommand(options = {}) {
         options.customLlm !== void 0 && "--custom-llm"
       ].filter(Boolean);
       if (simpleFlags.length > 0) {
-        throwValidation16(
+        throwValidation17(
           `--file is mutually exclusive with ${simpleFlags.join(", ")}. Put all fields in the JSON body.`
         );
       }
@@ -4992,12 +5003,12 @@ async function createChatAgentCommand(options = {}) {
         options.customLlm
       ].filter(Boolean).length;
       if (engineCount === 0) {
-        throwValidation16(
+        throwValidation17(
           "Must specify one of: --llm-id, --flow-id, or --custom-llm (or use --file)"
         );
       }
       if (engineCount > 1) {
-        throwValidation16(
+        throwValidation17(
           "Only one of --llm-id, --flow-id, or --custom-llm can be specified"
         );
       }
@@ -5029,7 +5040,7 @@ async function createChatAgentCommand(options = {}) {
     handleSdkError(error);
   }
 }
-function throwValidation16(message) {
+function throwValidation17(message) {
   const err = new Error(message);
   err.name = "ValidationError";
   throw err;
@@ -5277,6 +5288,75 @@ async function agentMcpToolsCommand(agentId, options) {
   }
 }
 
+// src/commands/playground/complete.ts
+async function playgroundCompleteCommand(agentId, options) {
+  try {
+    const params = {
+      messages: parseJsonArray(options.messages, "--messages")
+    };
+    const dynamicVariables = loadJsonArg(
+      options.dynamicVariables,
+      "--dynamic-variables"
+    );
+    if (dynamicVariables !== void 0) {
+      params.dynamic_variables = parseJsonObject(
+        dynamicVariables,
+        "--dynamic-variables"
+      );
+    }
+    const toolMocks = loadJsonArg(options.toolMocks, "--tool-mocks");
+    if (toolMocks !== void 0) {
+      params.tool_mocks = parseJsonArray(toolMocks, "--tool-mocks");
+    }
+    if (options.currentState !== void 0) {
+      params.current_state = requireNonEmpty(
+        options.currentState,
+        "--current-state"
+      );
+    }
+    if (options.currentNodeId !== void 0) {
+      params.current_node_id = requireNonEmpty(
+        options.currentNodeId,
+        "--current-node-id"
+      );
+    }
+    if (options.componentId !== void 0) {
+      params.component_id = requireNonEmpty(options.componentId, "--component-id");
+    }
+    if (options.version !== void 0) {
+      params.version = parseNumericFlag(options.version, "--version");
+    }
+    const client = getRetellClient();
+    const result = await client.playground.completion(
+      requireNonEmpty(agentId, "<agent_id>"),
+      params
+    );
+    const selectedFields = options.fields ? options.fields.split(",").map((f) => f.trim()).filter((f) => f.length > 0) : [];
+    const output = selectedFields.length > 0 ? filterFields(result, selectedFields) : result;
+    outputJson(output);
+  } catch (error) {
+    handleSdkError(error);
+  }
+}
+function parseJsonArray(value, flagName) {
+  const parsed = typeof value === "string" ? loadJsonArg(value, flagName) : value;
+  if (!Array.isArray(parsed)) {
+    throwValidation18(`${flagName} must be a JSON array`);
+  }
+  return parsed;
+}
+function parseJsonObject(value, flagName) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throwValidation18(`${flagName} must be a JSON object`);
+  }
+  return value;
+}
+function throwValidation18(message) {
+  const err = new Error(message);
+  err.name = "ValidationError";
+  throw err;
+}
+
 // src/index.ts
 var packageJson = JSON.parse(
   (0, import_fs19.readFileSync)((0, import_path6.join)(__dirname, "../package.json"), "utf-8")
@@ -6287,9 +6367,24 @@ calls.command("update <call_id>").description("Update metadata and storage setti
 ).option("--fields <fields>", "Comma-separated list of fields to return").action(async (callId, options) => {
   await updateCallCommand(callId, options);
 });
+calls.command("stop <call_id>").description("Stop an ongoing call").action(async (callId) => {
+  await stopCallCommand(callId);
+});
 calls.command("delete <call_id>").description("Delete a call and its associated data").action(async (callId) => {
   await deleteCallCommand(callId);
 });
+var exportsCommand = program.command("exports").description("Manage export requests");
+exportsCommand.command("list").description("List export requests").option("--limit <number>", "Maximum number of export requests to return").option("--pagination-key <key>", "Pagination key for the next page").option("--sort-order <order>", "ascending or descending").option("--fields <fields>", "Comma-separated list of fields to return").addHelpText(
+  "after",
+  `
+Examples:
+  $ retell exports list
+  $ retell exports list --limit 20 --sort-order descending
+  $ retell exports list --fields items.0.export_request_id,pagination_key
+    `
+).action(async (options) => {
+  await listExportRequestsCommand(options);
+});
 var batchCalls = program.command("batch-calls").description("Schedule bulk outbound calls");
 batchCalls.command("create").description("Create a new batch call").requiredOption("--from-number <number>", "Caller number in E.164 format").requiredOption(
   "--tasks <path>",
@@ -6415,6 +6510,23 @@ chats.command("sms").description("Create an SMS-backed chat session").requiredOp
 chats.command("end <chat_id>").description("End an active chat session").action(async (chatId) => {
   await endChatCommand(chatId);
 });
+var playground = program.command("playground").description("Run stateless playground completions");
+playground.command("complete <agent_id>").description("Run a stateless playground completion").requiredOption(
+  "--messages <json>",
+  "Conversation history as inline JSON array or @path"
+).option(
+  "--dynamic-variables <json>",
+  "Inline JSON object or @path for dynamic variables"
+).option("--tool-mocks <json>", "Inline JSON array or @path for tool mocks").option("--current-state <name>", "Current Retell-LLM state").option("--current-node-id <id>", "Current conversation-flow node id").option("--component-id <id>", "Conversation-flow component id").option("--version <number>", "Agent version to use").option("--fields <fields>", "Comma-separated list of fields to return").addHelpText(
+  "after",
+  `
+Examples:
+  $ retell playground complete agent_abc --messages '[{"role":"user","content":"Hi"}]'
+  $ retell playground complete agent_abc --messages @messages.json --dynamic-variables '{"name":"Ada"}'
+    `
+).action(async (agentId, options) => {
+  await playgroundCompleteCommand(agentId, options);
+});
 var chatAgents = program.command("chat-agents").description("Manage chat agents (text/SMS mode)");
 chatAgents.command("list").description("List chat agents").option("-l, --limit <n>", "Maximum number to return").option("--pagination-key <key>", "Chat agent id to start from").option(
   "--pagination-key-version <n>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retell-cli",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Community CLI for Retell AI - efficient access to transcripts, agents, and prompts for AI assistants without MCP overhead",
   "main": "dist/index.js",
   "bin": {
@@ -48,13 +48,13 @@
   },
   "homepage": "https://github.com/awccom/retell-cli#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.10.0"
   },
   "dependencies": {
     "commander": "^14.0.0",
     "dotenv": "^17.0.0",
     "microdiff": "^1.5.0",
-    "retell-sdk": "^5.12.0",
+    "retell-sdk": "^5.18.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {