retell-cli 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,368 @@ 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).
 
+## [Unreleased] - v1.0.1
+
+### Added - Phase 1: Foundation & Utilities
+
+#### Security
+- Prototype pollution protection in field path handling
+  - Rejects `__proto__`, `constructor`, and `prototype` keys
+  - Prevents object prototype manipulation attacks
+  - Comprehensive test coverage for security scenarios
+
+#### TypeScript Types
+- `DiffResult` and `ChangeDetail` - Types for prompt diffing functionality
+- `HotspotIssue` and `HotspotsResult` - Types for hotspot detection
+- `SearchOptions` and `SearchResult` - Types for search functionality
+- `FieldFilterOptions` and `FilteredResult` - Types for field filtering
+
+#### Utility Functions
+
+**Field Filtering (`src/services/output-formatter.ts`)**
+- `filterFields()` - Filter objects to include only specified fields
+  - Support for dot notation (e.g., `"user.profile.name"`)
+  - Handles nested objects and arrays gracefully
+  - Strict and non-strict modes for error handling
+  - Preserves data types when filtering (including `undefined` and `null`)
+  - Distinguishes between missing fields and `undefined` values
+  - Generic types for improved type inference
+  - Prototype pollution protection
+  - Comprehensive error messages for invalid fields
+
+**Prompt Diffing (`src/services/prompt-diff.ts`)**
+- `generateDiff()` - Compare local and remote prompt versions
+  - Supports retell-llm and conversation-flow agent types
+  - Detects added, removed, and modified fields
+  - Handles deeply nested objects and arrays
+  - Type-safe integration with existing PromptSource types
+  - Uses `microdiff` for reliable, maintained diffing
+  - Preserves primitive types without unnecessary conversion
+- `formatDiffSummary()` - Format diff results as human-readable summary
+
+#### Testing
+- 27 unit tests for `filterFields()` utility
+  - Top-level and nested field selection
+  - Array handling
+  - Invalid field handling (strict and non-strict modes)
+  - Edge cases (null, undefined, empty data)
+  - Real-world scenarios (Retell API objects)
+  - Security: Prototype pollution protection (4 tests)
+  - Undefined vs missing field distinction
+
+- 15 unit tests for `generateDiff()` utility
+  - Retell-LLM prompt changes
+  - Conversation-flow prompt changes
+  - No changes detection
+  - Error handling (type mismatches, custom-llm)
+  - Summary formatting
+
+- 1 helper function test
+  - `hasNestedPath()` with security validation
+
+- **Total: 43 tests passing** ✅
+
+#### Dependencies
+- `microdiff` - For detecting changes in prompt objects
+  - Actively maintained (vs. unmaintained `deep-diff`)
+  - Smaller bundle size
+  - Simpler, more modern API
+  - Better TypeScript support
+
+#### Developer Tools
+- `npm test` - Run all tests once
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Generate coverage report
+
+### Technical Details
+
+**Phase 1** provides foundation utilities that will be used by upcoming features:
+- Field selection (`--fields` flag) - Uses `filterFields()`
+- Raw output mode (`--raw` flag) - Will use field filtering
+- Hotspots detection (`--hotspots-only`) - Will use types and field filtering
+- Search command - Will use SearchOptions types and filtering
+- Diff & dry-run - Uses `generateDiff()` and `formatDiffSummary()`
+
+These utilities are designed to be:
+- **Performant** - Handle large objects efficiently
+- **Type-safe** - Full TypeScript support with generics
+- **Well-tested** - Comprehensive unit test coverage
+- **Documented** - JSDoc comments for all public APIs
+- **Reusable** - Clean, focused functions for multiple use cases
+- **Secure** - Protection against prototype pollution attacks
+
+### Added - Phase 2: Field Selection
+
+#### Field Selection Flag (`--fields`)
+- Added `--fields` option to transcript commands:
+  - `retell transcripts list --fields <fields>`
+  - `retell transcripts get <call_id> --fields <fields>`
+  - `retell transcripts analyze <call_id> --fields <fields>`
+
+- Added `--fields` option to agent commands:
+  - `retell agents list --fields <fields>`
+  - `retell agents info <agent_id> --fields <fields>`
+
+**Features:**
+- Comma-separated field list: `call_id,status,metadata.duration`
+- Dot notation for nested fields: `metadata.duration`
+- Handles whitespace in field lists
+- Graceful handling of invalid field names (warns, continues)
+- Reduces output size by 50-90% for typical AI workflows
+- Fully backward compatible (no --fields = full output)
+
+**Examples:**
+```bash
+# Select specific fields
+retell transcripts list --fields call_id,call_status
+
+# Nested field selection
+retell transcripts get abc123 --fields metadata.duration,analysis.summary
+
+# Combined with other options
+retell agents list --limit 10 --fields agent_id,agent_name
+```
+
+#### Documentation Updates
+- Added "Field Selection" section to README.md
+  - Usage examples with dot notation
+  - Supported commands list
+  - Token reduction benefits for AI workflows
+- Updated command examples in CLI help text
+
+#### Testing
+- All existing tests still passing (46/46) ✅
+- Backward compatibility verified
+- Manual testing completed for all edge cases
+
+### Added - Phase 3: Raw Output Mode
+
+#### Raw Output Flag (`--raw`)
+- Added `--raw` option to `transcripts analyze` command:
+  - `retell transcripts analyze <call_id> --raw`
+
+**Features:**
+- Returns unmodified [Call Object](https://docs.retellai.com/api-references/retrieve-call) from Retell API (bypasses enrichment)
+- Works seamlessly with `--fields` for combined filtering: `--raw --fields call_id,transcript`
+- Useful for debugging, API schema alignment, and accessing new fields
+- Fully backward compatible (no `--raw` = enriched analysis output)
+
+**Examples:**
+```bash
+# Get raw API response (official Retell schema)
+retell transcripts analyze abc123 --raw
+
+# Raw response with field filtering
+retell transcripts analyze abc123 --raw --fields call_id,transcript_object
+
+# Compare raw vs enriched
+diff <(retell transcripts analyze abc123 --raw) <(retell transcripts analyze abc123)
+```
+
+**Use Cases:**
+- Debugging: Compare raw API response to enriched output
+- API Schema Alignment: Tools expecting [official Retell API schema](https://docs.retellai.com/api-references/list-calls)
+- Future-proofing: Access new API fields before CLI enriches them
+- Token Efficiency: Combine with `--fields` for precise extraction
+
+#### Testing
+- All existing tests still passing (46/46) ✅
+- New integration tests added for raw mode (8 test cases)
+- Backward compatibility verified (no `--raw` = enriched output)
+- Manual testing completed for all use cases
+
+### Added - Phase 4: Hotspot Detection
+
+#### Hotspot Detection Flag (`--hotspots-only`)
+- Added `--hotspots-only` option to `transcripts analyze` command:
+  - `retell transcripts analyze <call_id> --hotspots-only`
+
+**Features:**
+- Detects conversation issues using Retell API metrics
+- Returns structured array of hotspots with turn indices and timestamps
+- Configurable thresholds for latency and silence detection
+- Works seamlessly with `--fields` for token efficiency
+- Fully backward compatible
+
+**Detected Issues:**
+- Latency spikes (p90 > configurable threshold, default 2000ms)
+- Long silences (gaps > configurable threshold, default 5000ms)
+- Sentiment issues (negative sentiment indicators)
+
+**Examples:**
+```bash
+# Detect all hotspots
+retell transcripts analyze abc123 --hotspots-only
+
+# Custom thresholds
+retell transcripts analyze abc123 --hotspots-only --latency-threshold 1500
+
+# Minimal output
+retell transcripts analyze abc123 --hotspots-only --fields hotspots
+```
+
+**Use Cases:**
+- Rapid troubleshooting: Identify problem areas in failed calls
+- Prompt iteration: See exactly where agent responses failed
+- Performance monitoring: Track latency issues across calls
+- AI workflows: Feed hotspots into prompt refinement pipelines
+
+#### Documentation
+- Added `localdocs/retell-api-metrics-reference.md` - API research findings
+- Updated README.md with "Hotspot Detection" section
+- Updated CLI help text with examples
+
+#### Testing
+- All existing tests still passing (59/59) ✅
+- Manual testing completed for all hotspot types
+- Edge cases verified (empty transcripts, missing metrics)
+- Backward compatibility verified
+
+### Added - Phase 5: Transcripts Search Command
+
+#### Advanced Search with Hybrid Filtering
+- Added `retell transcripts search` command with multiple filter options:
+  - `--status` - Filter by call status (error, ended, ongoing)
+  - `--agent-id` - Filter by agent ID
+  - `--since` - Filter calls after date (YYYY-MM-DD or ISO format)
+  - `--until` - Filter calls before date (YYYY-MM-DD or ISO format)
+  - `--limit` - Maximum results (default: 50)
+  - `--fields` - Select specific fields (Phase 2 integration)
+
+**Features:**
+- API-based filtering (100% server-side) for maximum performance
+- Structured output with results, total_count, and filters_applied
+- Input validation with helpful error messages
+- Seamless integration with `--fields` for token efficiency
+- Eliminates need for jq/grep in AI agent workflows
+- ISO date format support (YYYY-MM-DD and full ISO 8601)
+
+**Examples:**
+```bash
+# Find error calls for specific agent
+retell transcripts search --status error --agent-id agent_123
+
+# Date range filtering
+retell transcripts search --since 2025-11-01 --until 2025-11-15
+
+# Minimal output with field selection
+retell transcripts search --status error --fields call_id,call_status
+```
+
+**Use Cases:**
+- Batch analysis: Find and analyze problematic calls
+- Performance monitoring: Track errors by agent or time period
+- AI workflows: Automated issue detection without shell scripting
+- Debugging: Quickly locate specific call patterns
+
+#### Documentation
+- Added `localdocs/retell-api-search-capabilities.md` - API research findings
+- Updated README.md with "Search Transcripts" section
+- Updated CLI help text with comprehensive examples
+
+#### Testing
+- All existing tests still passing (78/78) ✅
+- 31 new unit tests for search validation and filtering
+- Manual testing completed for all filter combinations
+- Edge cases verified (empty results, invalid inputs)
+- Integration with `--fields` verified
+
+**Total: 109 tests passing** ✅
+
+### Fixed - Phase 1: Code Review Improvements
+
+#### Critical Bug Fixes
+- Fixed index bug in `setNestedValue()` helper function
+  - Was using `keys.indexOf(key)` which returns first occurrence, not current iteration index
+  - Now uses proper loop index variable for correct array/object type detection
+- Fixed undefined value handling in `filterFields()`
+  - Now correctly distinguishes between fields that don't exist vs. fields with `undefined` values
+  - Uses `hasNestedPath()` to check existence before checking value
+  - Preserves `undefined` values in filtered results when field exists
+
+#### Security Fixes
+- Added prototype pollution protection
+  - Validates field paths before processing
+  - Rejects dangerous keys: `__proto__`, `constructor`, `prototype`
+  - Prevents object prototype manipulation attacks
+  - Applies to both `hasNestedPath()` and `setNestedValue()` functions
+
+#### Dependency Updates
+- Replaced `deep-diff` with `microdiff`
+  - `deep-diff` hasn't been updated since 2018 (unmaintained)
+  - `microdiff` is actively maintained with regular updates
+  - Smaller bundle size and simpler API
+  - Better TypeScript support
+  - Preserves primitive types without unnecessary string conversion
+
+#### Type Safety Improvements
+- Added generic types to `filterFields()`
+  - Better type inference for return values
+  - Conditional return type based on input (array vs object)
+  - Maintains type safety while keeping flexibility
+
+
+### Added - Phase 6: Diff Command & Dry Run
+
+#### Prompt Diff & Dry Run
+- **`retell prompts diff <agent_id>`** - New command to show differences between local and remote prompts
+  - Compare prompts before applying updates
+  - Structured diff output with old/new values and change types
+  - Supports both retell-llm and conversation-flow agent types
+  - `--source` option for custom prompt directories
+  - `--fields` option for filtering diff output
+- **`--dry-run` flag for `retell prompts update`** - Preview changes without applying them
+  - Shows same structured diff as `prompts diff` command
+  - Prevents accidental prompt updates
+  - Useful for validating changes before publishing
+
+#### Shared Prompt Loading
+- **`loadLocalPrompts()` utility** - Centralized prompt loading from local files
+  - Eliminates code duplication between diff and update commands (112 lines removed)
+  - Validates prompt directory structure
+  - Handles both retell-llm and conversation-flow formats
+
+#### Enhanced Prompt Update Command
+- Added dry-run capability to preview changes
+- Improved error messages for type mismatches
+- Better validation of local prompt files
+
+#### AI Agent Workflows Documentation
+- **`docs/ai-agent-workflows.md`** - Comprehensive best practices guide
+  - Safe prompt update workflows
+  - Token efficiency strategies
+  - Call analysis patterns
+  - Iterative refinement workflows
+  - Error handling guidelines
+  - Common automation patterns
+
+**Use Cases:**
+- **Prevent Accidental Updates** - See exactly what will change before pushing
+- **AI Justification** - AI agents can explain changes by showing diffs
+- **Code Review for Prompts** - Review prompt changes like code PRs
+- **Debugging Support** - Compare local vs remote when troubleshooting
+- **Audit Trail** - Document what changed and when
+
+**Examples:**
+```bash
+# Compare local and remote prompts
+retell prompts diff agent_123
+
+# Preview changes before applying
+retell prompts update agent_123 --dry-run
+
+# Apply changes after review
+retell prompts update agent_123
+```
+
+**Technical Details:**
+- New services: `prompt-diff.ts`, `prompt-loader.ts`
+- New command: `prompts/diff.ts`
+- Enhanced: `prompts/update.ts` with dry-run support
+- Code deduplication: Removed 112 duplicate lines
+- No breaking changes - all new features are opt-in
+
+
 ## [1.0.0] - 2025-11-15
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/retell-cli.svg)](https://www.npmjs.com/package/retell-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Official command-line tool for Retell AI - analyze call transcripts and manage agent prompts.
+Community-built command-line tool for Retell AI - designed to give AI assistants efficient access to transcripts, agents, and prompts without using context-expensive MCP servers.
 
 ## Features
 
@@ -94,15 +94,18 @@ retell transcripts analyze call_abc123
 
 ```bash
 # Pull current prompts
-retell prompts pull agent_123abc --output prompts.json
+retell prompts pull agent_123abc
+
+# Edit .retell-prompts/agent_123abc/general_prompt.md with your changes
 
-# Edit prompts.json with your changes
+# Check what changed
+retell prompts diff agent_123abc
 
-# Update agent with new prompts (dry run first)
-retell prompts update agent_123abc --source prompts.json --dry-run
+# Dry run to preview changes
+retell prompts update agent_123abc --dry-run
 
 # Apply changes
-retell prompts update agent_123abc --source prompts.json
+retell prompts update agent_123abc
 
 # Publish the updated agent
 retell agent-publish agent_123abc
@@ -234,6 +237,42 @@ retell prompts pull agent_123abc
 retell prompts pull agent_123abc --output my-prompts.json
 ```
 
+#### `retell prompts diff <agent_id> [options]`
+
+Show differences between local and remote prompts before applying updates.
+
+**Options:**
+- `-s, --source <path>` - Source directory path (default: `.retell-prompts`)
+- `-f, --fields <fields>` - Comma-separated list of fields to return
+
+**Examples:**
+```bash
+# Compare local and remote prompts
+retell prompts diff agent_123abc
+
+# Use custom source directory
+retell prompts diff agent_123abc --source ./custom-prompts
+
+# Show only specific fields
+retell prompts diff agent_123abc --fields has_changes,changes.general_prompt
+```
+
+**Output:**
+```json
+{
+  "agent_id": "agent_123abc",
+  "agent_type": "retell-llm",
+  "has_changes": true,
+  "changes": {
+    "general_prompt": {
+      "old": "You are a helpful assistant...",
+      "new": "You are a helpful assistant specializing in...",
+      "change_type": "modified"
+    }
+  }
+}
+```
+
 #### `retell prompts update <agent_id> [options]`
 
 Update agent prompts from a local file.
@@ -265,6 +304,134 @@ Publish a draft agent to make changes live.
 retell agent-publish agent_123abc
 ```
 
+### Field Selection
+
+Reduce output size and token usage by selecting specific fields:
+
+```bash
+# Get only call_id and status
+retell transcripts list --fields call_id,call_status
+
+# Select nested fields with dot notation
+retell transcripts get abc123 --fields metadata.duration,analysis.summary
+
+# Combine with other options
+retell agents list --limit 10 --fields agent_id,agent_name
+```
+
+**Supported commands:**
+- All transcript commands (`list`, `get`, `analyze`)
+- All agent commands (`list`, `info`)
+
+**Features:**
+- Dot notation for nested fields (e.g., `metadata.duration`)
+- Works with arrays
+- Reduces token usage by 50-90% for AI workflows
+- Backward compatible (no --fields = full output)
+
+### Raw Output Mode
+
+Get the unmodified API response instead of enriched analysis:
+
+```bash
+# Raw API response (useful for debugging)
+retell transcripts analyze abc123 --raw
+
+# Combine with field selection for minimal output
+retell transcripts analyze abc123 --raw --fields call_id,transcript_object
+
+# Compare raw vs enriched
+retell transcripts analyze abc123 --raw > raw.json
+retell transcripts analyze abc123 > enriched.json
+diff raw.json enriched.json
+```
+
+**When to use:**
+- Debugging issues with API responses
+- When tools expect the official Retell API schema
+- Accessing new API fields before CLI enrichment support
+- Comparing raw data to enriched output for validation
+
+**Supported commands:**
+- `transcripts analyze` - returns the raw [Call Object](https://docs.retellai.com/api-references/retrieve-call) exactly as documented in the Retell API reference
+
+**Note:** The `--raw` flag works seamlessly with `--fields` for precise data extraction. Raw output returns the official Retell API schema, allowing you to access all fields documented in the [API reference](https://docs.retellai.com/api-references/list-calls).
+
+### Hotspot Detection
+
+Identify conversation issues for focused troubleshooting:
+
+```bash
+# Find all issues in a call
+retell transcripts analyze abc123 --hotspots-only
+
+# Combine with field selection
+retell transcripts analyze abc123 --hotspots-only --fields hotspots
+
+# Set custom thresholds
+retell transcripts analyze abc123 --hotspots-only --latency-threshold 1500
+retell transcripts analyze abc123 --hotspots-only --silence-threshold 3000
+```
+
+**Detected issues:**
+- **Latency spikes** - When p90 latency exceeds threshold (default: 2000ms)
+- **Long silences** - Gaps between turns exceeding threshold (default: 5000ms)
+- **Sentiment** - Negative sentiment indicators
+
+**Use cases:**
+- Rapid troubleshooting of failed calls
+- Prompt iteration and refinement
+- Performance monitoring across calls
+- AI agent workflow optimization
+
+**Note:** The `--hotspots-only` flag works seamlessly with `--fields` for token efficiency.
+
+### Search Transcripts
+
+Find calls with advanced filtering - no need for jq or grep:
+
+```bash
+# Find all error calls
+retell transcripts search --status error
+
+# Find calls for specific agent in date range
+retell transcripts search \
+  --agent-id agent_123 \
+  --since 2025-11-01 \
+  --until 2025-11-15
+
+# Combine multiple filters
+retell transcripts search \
+  --status error \
+  --agent-id agent_123 \
+  --since 2025-11-01 \
+  --limit 20
+
+# Use field selection for minimal output
+retell transcripts search \
+  --status error \
+  --fields call_id,call_status,agent_id
+```
+
+**Available filters:**
+- `--status` - Call status (error, ended, ongoing)
+- `--agent-id` - Filter by agent
+- `--since` - Calls after date (YYYY-MM-DD or ISO format)
+- `--until` - Calls before date (YYYY-MM-DD or ISO format)
+- `--limit` - Max results (default: 50)
+- `--fields` - Select specific fields (from Phase 2)
+
+**AI Agent Workflow Example:**
+```bash
+# 1. Find all recent error calls
+retell transcripts search --status error --since 2025-11-08 --fields call_id
+
+# 2. For each call, get hotspots
+retell transcripts analyze <call_id> --hotspots-only
+
+# 3. No jq or grep needed - direct JSON parsing!
+```
+
 ## Common Workflows
 
 ### Analyzing Failed Calls
@@ -319,7 +486,17 @@ jq -s '[.[] | .performance.latency_p50_ms.e2e] | add / length' analysis-*.json
 
 ## For AI Agents
 
-All commands output JSON by default, making this CLI perfect for AI coding assistants like Claude Code, Cursor, and GitHub Copilot.
+**This CLI was specifically designed for AI assistants** to access Retell AI efficiently without the token overhead of MCP servers. All commands output JSON by default, making it perfect for Claude Code, Cursor, Aider, and other AI coding assistants.
+
+### Why This Tool Exists
+
+Traditional MCP (Model Context Protocol) servers can consume significant context windows when working with Retell AI data. This CLI provides a lightweight, token-efficient alternative that:
+
+- **Reduces token usage by 50-90%** with field selection (`--fields`)
+- **Provides structured JSON output** for easy parsing
+- **Offers hotspot detection** for focused troubleshooting
+- **Enables safe prompt updates** with diff and dry-run features
+- **Works across all shells** (bash, zsh, fish) for maximum compatibility
 
 ### Example AI Workflow
 
@@ -331,12 +508,19 @@ retell transcripts list | jq '.[] | select(.call_status == "error")'
 retell transcripts analyze call_123
 
 # AI pulls current prompts
-retell prompts pull agent_456 --output current-prompts.json
+retell prompts pull agent_456
 
 # AI reads and suggests improvements to prompts
-# Then updates with improved version
-retell prompts update agent_456 --source improved-prompts.json --dry-run
-retell prompts update agent_456 --source improved-prompts.json
+# (Edits .retell-prompts/agent_456/general_prompt.md)
+
+# AI shows what changed
+retell prompts diff agent_456
+
+# AI explains the changes and uses dry-run to verify
+retell prompts update agent_456 --dry-run
+
+# Apply changes
+retell prompts update agent_456
 retell agent-publish agent_456
 ```
 
@@ -467,4 +651,4 @@ If you encounter any issues or have questions:
 
 ---
 
-Built with by the Retell AI community.
+Built by the community for AI-assisted Retell AI development. Not affiliated with or endorsed by Retell AI.