ToothFairyAI CLI (Node.js)

Command-line interface for interacting with ToothFairyAI agents.

Quick access: Use toothfairy command!

📦 Installation

From NPM

npm install -g @toothfairyai/cli

From Source

git clone <repository-url>
cd toothfairy-cli-js
npm install
npm link  # Makes 'toothfairy' command available globally

🌍 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 |

Configure for your region:

# 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:

toothfairy configure \
  --api-key "your-api-key" \
  --workspace-id "your-workspace-id"

2. Send a message to an agent:

toothfairy send "Hello, I need help with my appointment" \
  --agent-id "agent-123"

3. Search the knowledge hub:

toothfairy search "appointment scheduling help"

4. List your chats:

toothfairy chats

✨ 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

# 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_keyworkspace_id: your_workspace | | CLI arguments | Pass config file path | toothfairy --config /path/to/config.yml send ... |

Setting up configuration

Interactive Configuration

# 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

# 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:

# 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

# 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

• --config, -c: Path to configuration file
• --verbose, -v: Enable verbose logging and API debugging

Commands

configure

Set up CLI credentials and configuration.

Options:

• --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.

Arguments:

• message: The message text to send

Options:

• --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.

Arguments:

• query: The search query text

Options:

• --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:

• --output, -o: Output format (json|text)

chat <chat-id>

Get details of a specific chat.

Arguments:

• chat-id: The chat ID to retrieve

Options:

• --output, -o: Output format (json|text)

config-show

Display current configuration (with masked API key).

help-guide

Show detailed help with examples, common issues, and pro tips.

💡 Usage Examples

Basic Workflow

# Configure once
toothfairy configure --api-key "tf-key-abc123" --workspace-id "workspace-456"

# Send messages to agents
toothfairy send "I'd like to schedule a session" --agent-id "my-scheduler"

# Search for relevant information
toothfairy search "appointment scheduling help"

# Manage conversations
toothfairy chats
toothfairy chat chat-abc123

Scripting Examples

#!/bin/bash

# Send message and extract agent response
RESPONSE=$(toothfairy send "What are your hours?" \
  --agent-id "info-agent" \
  --output json)

# Extract the agent's text response
AGENT_TEXT=$(echo "$RESPONSE" | jq -r '.agentResponse.contents.content')
echo "Agent said: $AGENT_TEXT"

# 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"

# Get chat ID for follow-up
CHAT_ID=$(echo "$RESPONSE" | jq -r '.chatId')
echo "Chat ID: $CHAT_ID"

📦 SDK Usage

This package also provides a JavaScript SDK for programmatic access to ToothFairyAI.

Basic SDK Usage

const ToothFairyAPI = require('@toothfairyai/cli/src/api');

// Australia (default)
const api = new ToothFairyAPI(
  'https://api.toothfairyai.com',    // baseUrl
  'https://ai.toothfairyai.com',     // aiUrl
  'https://stream.toothfairyai.com', // aiStreamUrl
  'your-api-key',                    // apiKey
  'your-workspace-id',               // workspaceId
  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!',
  'agent-id',
  null, // phoneNumber
  null, // customerId
  null, // providerId
  {},   // customerInfo
  (eventType, data) => {
    console.log(`Event: ${eventType}`, data);
  }
);

Advanced SDK Features

Show Progress Flag

The SDK supports a showProgress flag that enables tracking of all events from the SSE endpoint:

// Default behavior (standard events only)
await api.sendMessageToAgentStream(
  'Hello!',
  'agent-id',
  null, null, null, {},
  (eventType, data) => {
    // Receives: 'status', 'progress', 'data', 'complete', 'error', etc.
    console.log(eventType, data);
  }
);

// With showProgress enabled (all SSE events)
await api.sendMessageToAgentStream(
  'Hello!',
  'agent-id',
  null, null, null, {},
  (eventType, data) => {
    if (eventType === 'sse_event') {
      // Raw SSE event with complete data from streaming endpoint
      console.log('Raw SSE event:', data);
    } else {
      // Standard processed events
      console.log('Standard event:', eventType, data);
    }
  },
  {}, // attachments
  true // showProgress = true
);

Event Types:

• 'status': Connection status ('connected', 'complete')
• 'progress': Agent processing status updates
• 'data': Streaming response text chunks
• 'complete': Final response with metadata
• 'error': Error events
• 'sse_event': All raw SSE events (when showProgress=true)

⚠️ 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 |

🐛 Troubleshooting

Debug Mode

Use the --verbose flag to see detailed API request/response information:

toothfairy --verbose send "test message" --agent-id "agent-123"
toothfairy search "test" --verbose

Configuration Issues

1. Check current configuration:

   toothfairy config-show

2. Verify credentials:

   toothfairy configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE

3. Test connection:

   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

# Install dependencies
npm install

# Run linter
npm run lint

# Run tests
npm test

# Link for local development
npm link

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Repository: ToothFairy CLI on Gitea
• NPM Package: @toothfairyai/cli on npm
• Issues: Report bugs and feature requests