@toothfairyai/cli 1.1.5 → 1.4.0

package/README.md

@@ -1,8 +1,10 @@
 # ToothFairyAI CLI (Node.js)
 
-A Node.js command-line interface for interacting with ToothFairyAI agents.
+**Command-line interface for interacting with ToothFairyAI agents.**
 
-## Installation
+**Quick access**: Use `toothfairy` command!
+
+## 📦 Installation
 
 ### From NPM
 ```bash
@@ -17,9 +19,39 @@ npm install
 npm link  # Makes 'toothfairy' command available globally
 ```
 
-## Quick Start
+## 🌍 Multi-Region Support
+
+ToothFairyAI operates in multiple regions. Configure your CLI to connect to the appropriate region:
+
+| Region | AI URL | API URL |
+|--------|--------|---------|
+| **Australia** (default) | https://ai.toothfairyai.com | https://api.toothfairyai.com |
+| **United States** | https://ai.us.toothfairyai.com | https://api.us.toothfairyai.com |
+| **Europe** | https://ai.eu.toothfairyai.com | https://api.eu.toothfairyai.com |
 
-1. **Configure your credentials:**
+### Configure for your region:
+```bash
+# Australia (default - no URLs needed)
+toothfairy configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE
+
+# United States
+toothfairy configure \
+  --api-key YOUR_KEY \
+  --workspace-id YOUR_WORKSPACE \
+  --ai-url https://ai.us.toothfairyai.com \
+  --base-url https://api.us.toothfairyai.com
+
+# Europe
+toothfairy configure \
+  --api-key YOUR_KEY \
+  --workspace-id YOUR_WORKSPACE \
+  --ai-url https://ai.eu.toothfairyai.com \
+  --base-url https://api.eu.toothfairyai.com
+```
+
+## 🚀 Quick Start
+
+1. **Configure your credentials and region:**
 ```bash
 toothfairy configure \
   --api-key "your-api-key" \
@@ -42,28 +74,178 @@ toothfairy search "appointment scheduling help"
 toothfairy chats
 ```
 
-## Available Commands
+## ✨ Features
+
+- **💬 Agent Communication**: Send messages to ToothFairyAI agents
+- **🔍 Knowledge Hub Search**: Search documents with advanced filtering
+- **📋 Chat Management**: List and view chat conversations
+- **⚙️ Configuration**: Flexible credential and settings management
+- **🎨 Rich Output**: Beautiful terminal interface with colors and tables
+- **📊 Multiple Formats**: JSON and text output for both interactive and scripted use
+- **🔐 Secure**: Safe credential storage and validation
+- **📱 Cross-Platform**: Works on Windows, macOS, and Linux
+- **🌍 Multi-Region**: Support for Australia, US, and EU regions
+- **📦 SDK Included**: Use as a library in your Node.js applications
+
+## 💬 Agent Communication Examples
+
+| Use Case | Command |
+|----------|---------|
+| Simple message | `toothfairy send "What are your hours?" --agent-id "info-agent"` |
+| With customer info | `toothfairy send "Schedule appointment" --agent-id "scheduler" --customer-info '{"name": "John"}'` |
+| Verbose output | `toothfairy send "Hello" --agent-id "agent-123" --verbose` |
+| JSON for scripting | `toothfairy send "Help" --agent-id "agent-123" --output json` |
+
+### Advanced Agent Communication
+```bash
+# Send message with detailed customer information
+toothfairy send "Check my insurance coverage" \
+  --agent-id "insurance-agent" \
+  --customer-info '{
+    "name": "Sarah Johnson",
+    "dateOfBirth": "1985-03-15",
+    "insurance": {
+      "provider": "BlueCross BlueShield",
+      "policyNumber": "BC123456789"
+    }
+  }'
+```
+
+## 🔍 Knowledge Hub Search Examples
+
+| Use Case | Command |
+|----------|---------|
+| Basic search | `toothfairy search "AI agent configuration"` |
+| Filter by status | `toothfairy search "machine learning" --status published` |
+| Limit results | `toothfairy search "troubleshooting" --top-k 3` |
+| Topic filtering | `toothfairy search "automation" --topics "topic_123,topic_456"` |
+| Specific document | `toothfairy search "settings" --document-id "doc_550..."` |
+| Verbose details | `toothfairy search "deployment" --verbose` |
+| JSON output | `toothfairy search "API docs" --output json` |
+
+### Search Filtering Guide
+
+Knowledge Hub search supports powerful filtering options:
+
+- **`--status`**: Filter documents by 'published' or 'suspended' status
+- **`--topics`**: Use topic IDs from ToothFairyAI (comma-separated)
+- **`--document-id`**: Search within a specific document
+- **`--top-k`**: Control number of results (1-50)
+- **`--verbose`**: Show relevance scores and metadata
+
+## 📋 Workspace Management Examples
+
+| Use Case | Command |
+|----------|---------|
+| List all chats | `toothfairy chats` |
+| View chat details | `toothfairy chat CHAT_ID` |
+| Show config | `toothfairy config-show` |
+| Detailed help | `toothfairy help-guide` |
+
+## ⚙️ Configuration
+
+The CLI supports multiple configuration methods (in order of priority):
+
+### Configuration Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| Environment | Set environment variables | `export TF_API_KEY=your_key` |
+| Config file | Use ~/.toothfairy/config.yml | `api_key: your_key`<br/>`workspace_id: your_workspace` |
+| CLI arguments | Pass config file path | `toothfairy --config /path/to/config.yml send ...` |
+
+### Setting up configuration
+
+#### Interactive Configuration
+```bash
+# Australia (default)
+toothfairy configure \
+  --api-key "your-api-key" \
+  --workspace-id "your-workspace-id"
+
+# United States
+toothfairy configure \
+  --api-key "your-api-key" \
+  --workspace-id "your-workspace-id" \
+  --base-url "https://api.us.toothfairyai.com" \
+  --ai-url "https://ai.us.toothfairyai.com"
+
+# Europe
+toothfairy configure \
+  --api-key "your-api-key" \
+  --workspace-id "your-workspace-id" \
+  --base-url "https://api.eu.toothfairyai.com" \
+  --ai-url "https://ai.eu.toothfairyai.com"
+
+# View current configuration
+toothfairy config-show
+```
+
+#### Environment Variables
+```bash
+# Required
+export TF_API_KEY="your-api-key"
+export TF_WORKSPACE_ID="your-workspace-id"
+
+# Optional - Region endpoints (defaults to Australia)
+# For US:
+export TF_BASE_URL="https://api.us.toothfairyai.com"
+export TF_AI_URL="https://ai.us.toothfairyai.com"
+
+# For EU:
+export TF_BASE_URL="https://api.eu.toothfairyai.com"
+export TF_AI_URL="https://ai.eu.toothfairyai.com"
+```
+
+#### Config File Format
+Create `~/.toothfairy/config.yml`:
+```yaml
+# Required
+api_key: "your-api-key"
+workspace_id: "your-workspace-id"
+
+# Optional - Region endpoints (defaults to Australia)
+# For US:
+base_url: "https://api.us.toothfairyai.com"
+ai_url: "https://ai.us.toothfairyai.com"
+
+# For EU:
+# base_url: "https://api.eu.toothfairyai.com"
+# ai_url: "https://ai.eu.toothfairyai.com"
+```
+
+## 📊 Output Formats
+
+The CLI supports `--output` or `-o` flag:
+
+- **`text`** (default): Pretty formatted tables and panels
+- **`json`**: Raw JSON output for scripting
+
+```bash
+# Get JSON output for scripting
+toothfairy send "Hello" --agent-id "agent-123" --output json | jq '.agentResponse.contents.content'
+
+# Search with JSON output
+toothfairy search "documentation" --output json | jq '.[].title'
+```
+
+## 🔧 Command Reference
 
 ### Global Options
-- `-c, --config <path>`: Path to configuration file
-- `-v, --verbose`: Enable verbose logging
+- `--config`, `-c`: Path to configuration file
+- `--verbose`, `-v`: Enable verbose logging and API debugging
 
 ### Commands
 
 #### `configure`
-Configure ToothFairy CLI credentials and settings.
+Set up CLI credentials and configuration.
 
 **Options:**
-- `--api-key <key>`: API key (required)
-- `--workspace-id <id>`: Workspace ID (required)
-- `--base-url <url>`: ToothFairy API base URL (optional, defaults to production)
-- `--ai-url <url>`: ToothFairyAI URL (optional, defaults to production)
-- `--config-path <path>`: Custom path to save config file
-
-**Example:**
-```bash
-toothfairy configure --api-key "your-key" --workspace-id "your-workspace"
-```
+- `--api-key`: API key (required)
+- `--workspace-id`: Workspace ID (required)
+- `--base-url`: ToothFairy API base URL (optional)
+- `--ai-url`: ToothFairyAI URL (optional)
+- `--config-path`: Custom path to save config file
 
 #### `send <message>`
 Send a message to a ToothFairyAI agent.
@@ -72,27 +254,13 @@ Send a message to a ToothFairyAI agent.
 - `message`: The message text to send
 
 **Options:**
-- `--agent-id <id>`: Agent ID to send message to (required)
-- `--phone-number <number>`: Phone number for SMS channel (optional)
-- `--customer-id <id>`: Customer ID (optional)
-- `--provider-id <id>`: SMS provider ID (optional)
-- `--customer-info <json>`: Customer info as JSON string (optional)
-- `-o, --output <format>`: Output format (json|text, default: text)
-- `-v, --verbose`: Show detailed response information
-
-**Examples:**
-```bash
-# Simple message
-toothfairy send "What are your hours?" --agent-id "info-agent"
-
-# With customer information
-toothfairy send "Schedule appointment" \
-  --agent-id "scheduler" \
-  --customer-info '{"name": "John", "phone": "+1234567890"}'
-
-# With verbose output
-toothfairy send "Hello" --agent-id "agent-123" --verbose
-```
+- `--agent-id`: Agent ID to send message to (required)
+- `--phone-number`: Phone number for SMS channel (optional)
+- `--customer-id`: Customer ID (optional)
+- `--provider-id`: SMS provider ID (optional)
+- `--customer-info`: Customer info as JSON string (optional)
+- `--output`, `-o`: Output format (json|text)
+- `--verbose`, `-v`: Show detailed response information
 
 #### `search <query>`
 Search for documents in the knowledge hub.
@@ -101,39 +269,18 @@ Search for documents in the knowledge hub.
 - `query`: The search query text
 
 **Options:**
-- `-k, --top-k <number>`: Number of documents to retrieve (1-50, default: 10)
-- `--status <status>`: Filter by document status (published|suspended)
-- `--document-id <id>`: Search within specific document ID
-- `--topics <topics>`: Comma-separated topic IDs to filter by
-- `-o, --output <format>`: Output format (json|text, default: text)
-- `-v, --verbose`: Show detailed search information
-
-**Examples:**
-```bash
-# Basic search
-toothfairy search "AI agent configuration"
-
-# Filter by status and limit results
-toothfairy search "machine learning" --status published --top-k 5
-
-# Search with topic filtering
-toothfairy search "automation" --topics "topic_123,topic_456"
-
-# Verbose search with JSON output
-toothfairy search "deployment" --verbose --output json
-```
+- `--top-k`, `-k`: Number of documents to retrieve (1-50, default: 10)
+- `--status`: Filter by document status (published|suspended)
+- `--document-id`: Search within specific document ID
+- `--topics`: Comma-separated topic IDs to filter by
+- `--output`, `-o`: Output format (json|text)
+- `--verbose`, `-v`: Show detailed search information
 
 #### `chats`
 List all chats in the workspace.
 
 **Options:**
-- `-o, --output <format>`: Output format (json|text, default: text)
-
-**Example:**
-```bash
-toothfairy chats
-toothfairy chats --output json
-```
+- `--output`, `-o`: Output format (json|text)
 
 #### `chat <chat-id>`
 Get details of a specific chat.
@@ -142,70 +289,56 @@ Get details of a specific chat.
 - `chat-id`: The chat ID to retrieve
 
 **Options:**
-- `-o, --output <format>`: Output format (json|text, default: text)
-
-**Example:**
-```bash
-toothfairy chat "chat-abc123"
-```
+- `--output`, `-o`: Output format (json|text)
 
 #### `config-show`
 Display current configuration (with masked API key).
 
-**Example:**
-```bash
-toothfairy config-show
-```
-
 #### `help-guide`
 Show detailed help with examples, common issues, and pro tips.
 
-**Example:**
-```bash
-toothfairy help-guide
-```
+## 💡 Usage Examples
 
-## Configuration
+### Basic Workflow
+```bash
+# Configure once
+toothfairy configure --api-key "tf-key-abc123" --workspace-id "workspace-456"
 
-The CLI supports multiple configuration methods (in order of priority):
+# Send messages to agents
+toothfairy send "I'd like to schedule a session" --agent-id "my-scheduler"
 
-1. **Environment variables:**
-```bash
-export TF_API_KEY="your-api-key"
-export TF_WORKSPACE_ID="your-workspace-id"
-export TF_BASE_URL="https://api.toothfairyai.com"  # optional
-export TF_AI_URL="https://ai.toothfairyai.com"     # optional
-```
+# Search for relevant information
+toothfairy search "appointment scheduling help"
 
-2. **Config file at `~/.toothfairy/config.yml`:**
-```yaml
-api_key: "your-api-key"
-workspace_id: "your-workspace-id"
-base_url: "https://api.toothfairyai.com"  # optional
-ai_url: "https://ai.toothfairyai.com"     # optional
+# Manage conversations
+toothfairy chats
+toothfairy chat chat-abc123
 ```
 
-3. **CLI arguments:**
+### Scripting Examples
 ```bash
-toothfairy --config /path/to/config.yml send "Hello" --agent-id "agent-123"
-```
+#!/bin/bash
 
-## Output Formats
+# Send message and extract agent response
+RESPONSE=$(toothfairy send "What are your hours?" \
+  --agent-id "info-agent" \
+  --output json)
 
-Both `json` and `text` output formats are supported:
+# Extract the agent's text response
+AGENT_TEXT=$(echo "$RESPONSE" | jq -r '.agentResponse.contents.content')
+echo "Agent said: $AGENT_TEXT"
 
-- **`text`** (default): Pretty formatted tables and panels
-- **`json`**: Raw JSON output for scripting
-
-```bash
-# Get JSON output for scripting
-toothfairy send "Hello" --agent-id "agent-123" --output json | jq '.agentResponse.contents.content'
+# Search documents and extract relevant content
+SEARCH_RESULTS=$(toothfairy search "office hours" --output json)
+TOP_RESULT=$(echo "$SEARCH_RESULTS" | jq -r '.[0].raw_text')
+echo "Found documentation: $TOP_RESULT"
 
-# Search with JSON output
-toothfairy search "documentation" --output json | jq '.[].title'
+# Get chat ID for follow-up
+CHAT_ID=$(echo "$RESPONSE" | jq -r '.chatId')
+echo "Chat ID: $CHAT_ID"
 ```
 
-## SDK Usage
+## 📦 SDK Usage
 
 This package also provides a JavaScript SDK for programmatic access to ToothFairyAI.
 
@@ -214,6 +347,7 @@ This package also provides a JavaScript SDK for programmatic access to ToothFair
 ```javascript
 const ToothFairyAPI = require('@toothfairyai/cli/src/api');
 
+// Australia (default)
 const api = new ToothFairyAPI(
   'https://api.toothfairyai.com',    // baseUrl
   'https://ai.toothfairyai.com',     // aiUrl
@@ -223,6 +357,26 @@ const api = new ToothFairyAPI(
   false                              // verbose mode
 );
 
+// United States
+const apiUS = new ToothFairyAPI(
+  'https://api.us.toothfairyai.com',    // baseUrl
+  'https://ai.us.toothfairyai.com',     // aiUrl
+  'https://stream.us.toothfairyai.com', // aiStreamUrl
+  'your-api-key',
+  'your-workspace-id',
+  false
+);
+
+// Europe
+const apiEU = new ToothFairyAPI(
+  'https://api.eu.toothfairyai.com',    // baseUrl
+  'https://ai.eu.toothfairyai.com',     // aiUrl
+  'https://stream.eu.toothfairyai.com', // aiStreamUrl
+  'your-api-key',
+  'your-workspace-id',
+  false
+);
+
 // Send a message with streaming response
 await api.sendMessageToAgentStream(
   'Hello!',
@@ -237,16 +391,18 @@ await api.sendMessageToAgentStream(
 );
 ```
 
-### New in v1.1.0: Show Progress Flag
+### Advanced SDK Features
+
+#### Show Progress Flag
 
-The SDK now supports a `showProgress` flag that enables tracking of all events from the SSE endpoint, similar to the CLI's `--show-progress` flag:
+The SDK supports a `showProgress` flag that enables tracking of all events from the SSE endpoint:
 
 ```javascript
 // Default behavior (standard events only)
 await api.sendMessageToAgentStream(
-  'Hello!', 
-  'agent-id', 
-  null, null, null, {}, 
+  'Hello!',
+  'agent-id',
+  null, null, null, {},
   (eventType, data) => {
     // Receives: 'status', 'progress', 'data', 'complete', 'error', etc.
     console.log(eventType, data);
@@ -255,9 +411,9 @@ await api.sendMessageToAgentStream(
 
 // With showProgress enabled (all SSE events)
 await api.sendMessageToAgentStream(
-  'Hello!', 
-  'agent-id', 
-  null, null, null, {}, 
+  'Hello!',
+  'agent-id',
+  null, null, null, {},
   (eventType, data) => {
     if (eventType === 'sse_event') {
       // Raw SSE event with complete data from streaming endpoint
@@ -280,16 +436,89 @@ await api.sendMessageToAgentStream(
 - `'error'`: Error events
 - `'sse_event'`: All raw SSE events (when showProgress=true)
 
-For full documentation and cross-platform examples, see the main [README.md](../README.md) in the parent directory.
+## ⚠️ Common Issues & Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Configuration incomplete | Run: `toothfairy configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE` |
+| No text response found | Use `--verbose` flag to see full response details |
+| Agent not responding | Check agent-id is correct and agent is active |
+| Network errors | Verify API endpoints are accessible and credentials are valid |
 
-## Development
+## 🐛 Troubleshooting
+
+### Debug Mode
+Use the `--verbose` flag to see detailed API request/response information:
 
 ```bash
+toothfairy --verbose send "test message" --agent-id "agent-123"
+toothfairy search "test" --verbose
+```
+
+### Configuration Issues
+1. **Check current configuration:**
+   ```bash
+   toothfairy config-show
+   ```
+
+2. **Verify credentials:**
+   ```bash
+   toothfairy configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE
+   ```
+
+3. **Test connection:**
+   ```bash
+   toothfairy chats --verbose
+   ```
+
+## 📖 More Help
+
+- **Command-specific help**: `toothfairy COMMAND --help`
+- **Detailed examples**: `toothfairy help-guide`
+- **Verbose debugging**: Use `--verbose` flag
+- **JSON output**: Use `--output json` for machine-readable output
+- **Configuration priority**: Environment variables → ~/.toothfairy/config.yml → CLI args
+
+## ✨ Pro Tips
+
+💾 **Save time**: Configure once with `toothfairy configure`, then just use `toothfairy send` and `toothfairy search`
+
+🔍 **Debug issues**: Use `--verbose` to see full API responses and troubleshoot
+
+📝 **Scripting**: Use `--output json` and tools like `jq` to parse responses
+
+⚡ **Quick tests**: Only `--agent-id` is required for send, only query for search
+
+🎯 **Better search**: Use `--status`, `--topics`, and `--document-id` for targeted results
+
+🔧 **Multiple environments**: Use different config files with `--config` flag
+
+🌍 **Regional performance**: Choose the region closest to you for best performance
+
+📦 **Use as SDK**: Import the API class in your Node.js applications for programmatic access
+
+## 👩‍💻 Development
+
+```bash
+# Install dependencies
 npm install
+
+# Run linter
 npm run lint
+
+# Run tests
 npm test
+
+# Link for local development
+npm link
 ```
 
-## License
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🔗 Links
 
-MIT
+- **Repository**: [ToothFairy CLI on Gitea](https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli)
+- **NPM Package**: [@toothfairyai/cli on npm](https://www.npmjs.com/package/@toothfairyai/cli)
+- **Issues**: [Report bugs and feature requests](https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli/issues)