ffmcp Documentation - Complete Guide | Installation, Commands, Examples

Installation

💡 Supporting ffmcp: ffmcp is free and open-source. If you find it useful, please consider sponsoring the project to support continued development and new features.

Install via pip (Recommended)

$ pip install ffmcp

📦 PyPI Package: https://pypi.org/project/ffmcp/
Note: On macOS with Homebrew Python, you may need to use a virtual environment. See "Install from Source" below for details.

Install with Specific Providers

$ pip install ffmcp[openai]      # OpenAI only
$ pip install ffmcp[anthropic]  # Anthropic only
$ pip install ffmcp[all]         # All providers

Install via npm

$ npm install -g ffmcp

📦 npm Package: https://www.npmjs.com/package/ffmcp
Note: The npm package requires the Python package to be installed separately. Install via pip first: pip install ffmcp

Install from Source (Development)

$ git clone https://github.com/brandonhenry/ffmcp.git
$ cd ffmcp
$ python3 -m venv venv
$ source venv/bin/activate  # On Windows: venv\Scripts\activate
$ pip install -e .

For Development: Use this method if you want to contribute or get the latest features before they're published to PyPI.

Quick Start

1. Get API Keys

You'll need API keys from the providers you want to use. Here's where to get them:

OpenAI: Get your API key from platform.openai.com/api-keys
Anthropic Claude: Get your API key from console.anthropic.com
Google Gemini: Get your API key from makersuite.google.com/app/apikey
Groq: Get your API key from console.groq.com
DeepSeek: Get your API key from platform.deepseek.com
Mistral AI: Get your API key from console.mistral.ai
Together AI: Get your API key from api.together.xyz
Cohere: Get your API key from dashboard.cohere.com
Perplexity AI: Get your API key from perplexity.ai/settings/api
ElevenLabs (TTS): Get your API key from elevenlabs.io → Profile → API Keys
FishAudio (TTS): Get your API key from fish.audio or your FishAudio provider
Zep (Brains/Memory): Get your API key from help.getzep.com/walkthrough (Zep Cloud) or configure for self-hosted

2. Configure API Keys

# Configure API keys using ffmcp config command
$ ffmcp config -p openai -k YOUR_OPENAI_API_KEY
$ ffmcp config -p anthropic -k YOUR_ANTHROPIC_API_KEY
$ ffmcp config -p gemini -k YOUR_GEMINI_API_KEY
$ ffmcp config -p groq -k YOUR_GROQ_API_KEY
$ ffmcp config -p deepseek -k YOUR_DEEPSEEK_API_KEY
$ ffmcp config -p mistral -k YOUR_MISTRAL_API_KEY
$ ffmcp config -p together -k YOUR_TOGETHER_API_KEY
$ ffmcp config -p cohere -k YOUR_COHERE_API_KEY
$ ffmcp config -p perplexity -k YOUR_PERPLEXITY_API_KEY
$ ffmcp config -p elevenlabs -k YOUR_ELEVENLABS_API_KEY
$ ffmcp config -p fishaudio -k YOUR_FISHAUDIO_API_KEY
$ ffmcp config -p zep -k YOUR_ZEP_API_KEY

# Or use environment variables (alternative method)
$ export OPENAI_API_KEY=your_key_here
$ export ANTHROPIC_API_KEY=your_key_here
$ export GEMINI_API_KEY=your_key_here
$ export GROQ_API_KEY=your_key_here
$ export DEEPSEEK_API_KEY=your_key_here
$ export MISTRAL_API_KEY=your_key_here
$ export TOGETHER_API_KEY=your_key_here
$ export COHERE_API_KEY=your_key_here
$ export PERPLEXITY_API_KEY=your_key_here
$ export ELEVENLABS_API_KEY=your_key_here
$ export FISHAUDIO_API_KEY=your_key_here
$ export ZEP_CLOUD_API_KEY=your_key_here

💡 Tip: You don't need all API keys at once. Start with one provider (like OpenAI) and add more as needed. Environment variables take precedence over config file settings.

⭐ Support ffmcp: If ffmcp helps you build amazing things, consider sponsoring the project to help fund continued development, new features, and improvements.

3. Test Basic Commands

# Get help
$ ffmcp --help
$ ffmcp generate --help
$ ffmcp openai --help

# Test text generation
$ ffmcp generate "Hello, world!" -p openai

# List available providers
$ ffmcp providers

Quick Reference: API Key Locations

Provider	Where to Get API Key
OpenAI	platform.openai.com/api-keys
Anthropic	console.anthropic.com
Gemini	makersuite.google.com/app/apikey
Groq	console.groq.com
DeepSeek	platform.deepseek.com
Mistral	console.mistral.ai
Together AI	api.together.xyz
Cohere	dashboard.cohere.com
Perplexity	perplexity.ai/settings/api
ElevenLabs	elevenlabs.io → Profile → API Keys
FishAudio	fish.audio or your provider
Zep	help.getzep.com/walkthrough (Zep Cloud)

Basic Commands

ffmcp generate: Generate text from a prompt
ffmcp chat: Chat conversationally with AI
ffmcp config: Manage API keys and configuration
ffmcp providers: List available AI providers
ffmcp openai: Access OpenAI-specific features (vision, images, audio, etc.)
ffmcp brain: Manage brains, memory, collections, and graph (Zep)
ffmcp agent: Create, manage, and run named agents
ffmcp team: Create, manage, and run hierarchical teams of agents

Text Generation

Simple Generation

$ ffmcp generate "Write a haiku about Python programming"

With Provider and Model

$ ffmcp generate "Explain quantum computing" -p openai -m gpt-4o-mini

Streaming Response

# See response as it generates (real-time)
$ ffmcp generate "Tell me a story" -s

Control Creativity (Temperature)

# Temperature range: 0.0 (deterministic) to 2.0 (very creative)
$ ffmcp generate "Creative story" -t 0.9

Limit Response Length

$ ffmcp generate "Summarize this" --max-tokens 100

With System Message

# Set the AI's role/personality
$ ffmcp generate "Solve this math problem" --system "You are a helpful math tutor"

Output Formats

# Output as JSON object
$ ffmcp generate "Write a haiku" --json

# Output as JSON array
$ ffmcp generate "Write a haiku" --array

Read from File

# Read prompt from file
$ ffmcp generate -i prompt.txt

# Write output to file
$ ffmcp generate "Write code" -o output.txt

# Both input and output files
$ ffmcp generate -i prompt.txt -o output.txt

Pipe Input

# Pipe text into ffmcp
$ echo "Translate to French: Hello world" | ffmcp generate

# Chain with other commands
$ cat document.txt | ffmcp generate | grep "important" > filtered.txt

Advanced Options

$ ffmcp generate "Creative story" \
  -p openai \
  -m gpt-4o \
  -t 0.9 \
  --max-tokens 500 \
  -s

Agents

Create an Agent

# Create a helpful assistant with a brain attached
$ ffmcp agent create myagent -p openai -m gpt-4o-mini -i "You are a helpful assistant" --brain mybrain

List, Use, Show

$ ffmcp agent list
$ ffmcp agent use myagent
$ ffmcp agent show

Run the Agent

$ ffmcp agent run "Plan a 3-day trip to Paris and fetch top sights"

Output Formats

# Output as JSON
$ ffmcp agent run "Write a summary" --json

# Output as array
$ ffmcp agent run "Write a summary" --array

Actions and Properties

# Enable/disable actions
$ ffmcp agent action enable myagent web_fetch
$ ffmcp agent action disable myagent generate_image

# Set/unset properties
$ ffmcp agent prop set myagent timezone UTC
$ ffmcp agent prop unset myagent timezone

Vision with Local Images

$ ffmcp agent run "What is in these photos?" --image photo1.jpg --image photo2.png

Hierarchical Teams

Agents can work together in hierarchical teams to accomplish complex tasks. Teams use an orchestrator agent at the top that orchestrates collaboration by delegating tasks to members or sub-teams. All activity flows up through the hierarchy, and the top orchestrator has visibility into everything through shared brain/memory.

Create a Simple Team

# Create specialized agents
$ ffmcp agent create researcher -p openai -m gpt-4o-mini -i "You are a research specialist"
$ ffmcp agent create writer -p openai -m gpt-4o-mini -i "You are a writing specialist"
$ ffmcp agent create orchestrator -p openai -m gpt-4o-mini -i "You orchestrate teams"

# Enable delegation for orchestrator
$ ffmcp agent action enable orchestrator delegate_to_agent

# Create a team with orchestrator and members
$ ffmcp team create research-team -o orchestrator -m researcher -m writer

Create a Team with Shared Brain

# Create shared brain for team memory (flows up hierarchy)
$ ffmcp brain create team-brain
$ ffmcp team create project-team -o orchestrator -m researcher -m writer -b team-brain

Create Nested Teams (Teams within Teams)

# Create sub-team orchestrators
$ ffmcp agent create sub-orchestrator-1 -p openai -m gpt-4o-mini -i "You coordinate a research sub-team"
$ ffmcp agent action enable sub-orchestrator-1 delegate_to_agent

$ ffmcp agent create sub-orchestrator-2 -p openai -m gpt-4o-mini -i "You coordinate a writing sub-team"
$ ffmcp agent action enable sub-orchestrator-2 delegate_to_agent

# Create sub-teams
$ ffmcp team create research-sub-team -o sub-orchestrator-1 -m researcher -b team-brain
$ ffmcp team create writing-sub-team -o sub-orchestrator-2 -m writer -b team-brain

# Create top-level team with sub-teams
$ ffmcp team create main-team -o orchestrator -s research-sub-team -s writing-sub-team -b team-brain

Run a Task with a Team

# Run a task - orchestrator delegates as needed
$ ffmcp team run "Research and write a comprehensive report on quantum computing" --team main-team

# Use active team (no --team flag needed)
$ ffmcp team use main-team
$ ffmcp team run "Create a summary of recent AI breakthroughs"

Output Formats

# Output as JSON
$ ffmcp team run "Create a report" --team main-team --json

# Output as array
$ ffmcp team run "Create a report" --team main-team --array

Manage Teams

# List all teams
$ ffmcp team list

# Show team details including hierarchy
$ ffmcp team show main-team

# Add/remove members and sub-teams
$ ffmcp team add-member main-team analyst
$ ffmcp team add-sub-team main-team analysis-sub-team
$ ffmcp team remove-member main-team analyst
$ ffmcp team remove-sub-team main-team analysis-sub-team

# Set a different orchestrator
$ ffmcp team set-orchestrator main-team new-orchestrator

How Hierarchical Teams Work

Orchestrator: One agent at the top level that receives tasks and orchestrates collaboration
Members: Direct agent members below the orchestrator
Sub-teams: Nested teams with their own orchestrators and members (supports multiple layers)
Shared Brain: Memory context that flows up the hierarchy - the top orchestrator sees all activity
Delegation: Orchestrators can delegate to members or sub-team orchestrators
Visibility: All activity flows up through the hierarchy, giving the top orchestrator complete visibility

Example Hierarchical Structure

main-team (orchestrator: ceo)
├── research-sub-team (orchestrator: research-manager)
│   ├── researcher-1
│   └── researcher-2
├── writing-sub-team (orchestrator: writing-manager)
│   ├── writer-1
│   └── writer-2
└── direct-member (analyst)

Chat Mode

Simple Chat

$ ffmcp chat "What is 2+2?" -p openai

With System Message

# Set the AI's role/personality
$ ffmcp chat "Solve this math problem" -s "You are a helpful math tutor" -p openai

Output Formats

# Output as JSON
$ ffmcp chat "Write a haiku" --json

# Output as array
$ ffmcp chat "Write a haiku" --array

OpenAI Features

🖼️ Image Generation (DALL·E)

# Generate image with DALL·E 3 (default)
$ ffmcp openai image "A futuristic cityscape at sunset"

# Use DALL·E 2 (cheaper, faster)
$ ffmcp openai image "A cat wearing sunglasses" -m dall-e-2

# Custom size (DALL·E 2 only)
$ ffmcp openai image "A cat wearing sunglasses" -m dall-e-2 --size 512x512

# High quality
$ ffmcp openai image "Abstract art" --quality hd

# Natural style (vs vivid)
$ ffmcp openai image "Portrait" --style natural

# Save URL to file
$ ffmcp openai image "Beautiful landscape" -o image_url.txt

👁️ Vision / Image Analysis

# Analyze a single image
$ ffmcp openai vision "What's in this image?" photo.jpg

# Analyze multiple images
$ ffmcp openai vision "Compare these images" img1.jpg img2.png

# With custom model and temperature
$ ffmcp openai vision "Describe this" photo.jpg -m gpt-4o -t 0.5

🎤 Audio Transcription (Whisper)

# Basic transcription
$ ffmcp openai transcribe audio.mp3

# With language hint (for better accuracy)
$ ffmcp openai transcribe spanish_audio.mp3 -l es

# With prompt (helps with technical terms, names, etc.)
$ ffmcp openai transcribe meeting.mp3 -p "This is a technical meeting about AI"

# Get JSON output with timestamps
$ ffmcp openai transcribe audio.mp3 --json -o transcript.json

# Save to text file
$ ffmcp openai transcribe audio.mp3 -o transcript.txt

🌍 Audio Translation

# Translate any audio to English
$ ffmcp openai translate spanish_audio.mp3

# With prompt for better accuracy
$ ffmcp openai translate audio.mp3 -p "Technical presentation"

🔊 Text-to-Speech

# Convert text to speech
$ ffmcp openai tts "Hello, world!" output.mp3

# Choose voice (alloy, echo, fable, onyx, nova, shimmer)
$ ffmcp openai tts "Welcome" speech.mp3 -v nova

# Adjust speed (0.25 to 4.0)
$ ffmcp openai tts "Important announcement" announcement.mp3 -s 1.2

# High quality model
$ ffmcp openai tts "Professional narration" narration.mp3 -m tts-1-hd

📊 Embeddings

# Create embeddings (for semantic search, similarity, etc.)
$ ffmcp openai embed "This is sample text"

# Custom dimensions
$ ffmcp openai embed "Vectorize this" -d 256

# Get full JSON with usage stats
$ ffmcp openai embed "Text to embed" --json -o embeddings.json

# Save to file
$ ffmcp openai embed "Important text" -o vectors.json

🔧 Function Calling / Tools

# First, create a tools.json file
$ cat > tools.json << 'EOF'
[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather in a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    }
  }
]
EOF

# Use function calling
$ ffmcp openai tools "What's the weather in San Francisco?" -t tools.json

🤖 Assistants API

# Create an assistant
$ ffmcp openai assistant create "Math Tutor" "You are a helpful math tutor" -o assistant_id.txt

# Create a conversation thread
$ ffmcp openai assistant thread -o thread_id.txt

# Add a message to the thread
$ ffmcp openai assistant message $(cat thread_id.txt) "Solve 2x + 5 = 15"

# Run the assistant
$ ffmcp openai assistant run $(cat thread_id.txt) $(cat assistant_id.txt)

# Get all messages from thread
$ ffmcp openai assistant messages $(cat thread_id.txt)

# Upload a file for the assistant to use
$ ffmcp openai assistant upload document.pdf

🎙️ TTS/Voiceover

ffmcp includes comprehensive text-to-speech (TTS) functionality supporting multiple providers including ElevenLabs and FishAudio. You can create voice configurations, discover voices, and generate speech from text.

Quick Start

# 1. Configure API key
$ ffmcp config -p elevenlabs -k YOUR_ELEVENLABS_API_KEY

# 2. Discover available voices
$ ffmcp voiceover provider list --provider elevenlabs

# 3. Create a voice configuration
$ ffmcp voiceover create my-voice \
  --provider elevenlabs \
  --voice-id 21m00Tcm4TlvDq8ikWAM \
  --description "My favorite voice"

# 4. Generate speech
$ ffmcp tts "Hello, world!" output.mp3 --voice my-voice

Voice Configuration Management

Create Voice Configuration

# Basic configuration
$ ffmcp voiceover create narrator \
  --provider elevenlabs \
  --voice-id 21m00Tcm4TlvDq8ikWAM

# With all settings (ElevenLabs)
$ ffmcp voiceover create narrator \
  --provider elevenlabs \
  --voice-id pNInz6obpgDQGcFmaJgB \
  --model-id eleven_multilingual_v2 \
  --stability 0.5 \
  --similarity-boost 0.75 \
  --style 0.0 \
  --use-speaker-boost \
  --output-format mp3_44100_128 \
  --description "Narrator voice for stories"

# FishAudio with reference audio (voice cloning)
$ ffmcp voiceover create cloned-voice \
  --provider fishaudio \
  --reference-audio /path/to/reference.wav \
  --reference-text "This is a sample of the voice I want to clone" \
  --format wav \
  --prosody-speed 1.0 \
  --description "Cloned voice from audio"

List and Manage Voices

# List all saved voices
$ ffmcp voiceover list

# Show voice details
$ ffmcp voiceover show my-voice

# Update voice settings
$ ffmcp voiceover update my-voice --stability 0.6 --similarity-boost 0.8

# Delete voice
$ ffmcp voiceover delete my-voice

Provider Voice Discovery

# List all voices from a provider
$ ffmcp voiceover provider list --provider elevenlabs
$ ffmcp voiceover provider list --provider fishaudio

# Show details of a specific voice
$ ffmcp voiceover provider show --provider elevenlabs 21m00Tcm4TlvDq8ikWAM

Text-to-Speech Generation

Using Saved Voice Configuration

# Simple usage with saved voice
$ ffmcp tts "Hello, this is a test" output.mp3 --voice my-voice

# Override specific settings
$ ffmcp tts "Custom settings test" output.mp3 \
  --voice my-voice \
  --stability 0.7 \
  --similarity-boost 0.9

Using Provider Directly

# ElevenLabs direct usage
$ ffmcp tts "Direct voice usage" output.mp3 \
  --provider elevenlabs \
  --voice-id 21m00Tcm4TlvDq8ikWAM \
  --model-id eleven_multilingual_v2 \
  --stability 0.5 \
  --similarity-boost 0.75 \
  --style 0.0 \
  --use-speaker-boost \
  --output-format mp3_44100_128

# FishAudio with reference ID
$ ffmcp tts "Hello from FishAudio" output.mp3 \
  --provider fishaudio \
  --reference-id my-model-id \
  --format mp3

# FishAudio with reference audio (one-time cloning)
$ ffmcp tts "This will sound like the reference" output.mp3 \
  --provider fishaudio \
  --reference-audio /path/to/reference.wav \
  --reference-text "Reference text" \
  --format wav \
  --prosody-speed 1.2

Voice Parameters Explained

Stability (0.0-1.0): Lower values (0.0-0.3): More variation, expressive. Higher values (0.7-1.0): More consistent, stable. Default: 0.5
Similarity Boost (0.0-1.0): How similar to the original voice. Higher = more similar. Default: 0.75
Style (0.0-1.0): Style exaggeration. Lower = neutral, Higher = expressive. Default: 0.0
Speaker Boost: Enhances clarity and intelligibility. Enabled by default.
Output Formats (ElevenLabs): mp3_44100_128 (default), mp3_44100_192, pcm_16000, pcm_22050, pcm_24000, pcm_44100
Output Formats (FishAudio): mp3, wav, pcm, opus
Prosody (FishAudio): Control speech speed (--prosody-speed) and volume (--prosody-volume)

Agent Voice Integration

# Create agent with voice
$ ffmcp agent create assistant \
  -p openai \
  -m gpt-4o-mini \
  -i "You are a helpful assistant" \
  --voice my-voice

# Set voice for existing agent
$ ffmcp agent voice set assistant my-voice

# Show agent's voice
$ ffmcp agent voice show assistant

# Remove voice from agent
$ ffmcp agent voice remove assistant

Supported Providers

ElevenLabs

Setup:

$ pip install elevenlabs
$ ffmcp config -p elevenlabs -k YOUR_ELEVENLABS_API_KEY

Get API key from elevenlabs.io

FishAudio

Setup:

$ pip install fish-audio-sdk
$ ffmcp config -p fishaudio -k YOUR_FISHAUDIO_API_KEY

FishAudio supports voice cloning with reference audio files

Advanced Usage

Batch TTS Generation

# Generate multiple files
$ for text in "Hello" "World" "Test"; do
    ffmcp tts "$text" "${text}.mp3" --voice my-voice
done

# Process text file line by line
$ counter=1
$ while IFS= read -r line; do
    ffmcp tts "$line" "output_${counter}.mp3" --voice my-voice
    counter=$((counter + 1))
done < input.txt

Voice Settings Experimentation

# Test different stability settings
$ for stability in 0.3 0.5 0.7 0.9; do
    ffmcp tts "Stability test: $stability" "stability_${stability}.mp3" \
      --voice my-voice \
      --stability $stability
done

Integration with Agent Responses

# Get agent response and convert to speech
$ response=$(ffmcp agent run "Explain quantum computing" --agent assistant)
$ ffmcp tts "$response" response.mp3 --voice assistant-voice

💡 Tips:

Use higher stability (0.7-0.9) for consistent narration
Use lower stability (0.3-0.5) with higher style (0.2-0.4) for expressive characters
For FishAudio voice cloning, use high-quality reference audio (16kHz+, 3-5 seconds minimum)
Create named voice configurations for common use cases
Use eleven_turbo_v2 model for faster generation
Use mp3_44100_192 or PCM formats for highest quality

Brains (Zep/LEANN Memory)

Backend Options:

Zep: Cloud or self-hosted memory platform (requires API key for cloud)
LEANN: Local vector index with 97% storage savings, runs entirely on your server (no API key needed)

Setup Zep

# Zep Cloud (recommended)
$ export ZEP_CLOUD_API_KEY=your_key

# Self-hosted Zep (optional)
$ export ZEP_BASE_URL=http://localhost:8000

# Or persist key
$ ffmcp config -p zep -k YOUR_ZEP_API_KEY

Setup LEANN

# LEANN works out of the box - no API key needed!
# Optional: Configure index directory (defaults to ~/.ffmcp/leann_indexes)
$ export LEANN_INDEX_DIR=/path/to/indexes

Create and Use a Brain

# Create a Zep brain (default)
$ ffmcp brain create my-zep-brain --backend zep

# Create a LEANN brain (local, no API key needed)
$ ffmcp brain create my-leann-brain --backend leann

# Create with default session ID
$ ffmcp brain create mybrain --session-id session-123

# List brains (shows backend type)
$ ffmcp brain list
# Output: my-zep-brain (zep) *
#         my-leann-brain (leann)

$ ffmcp brain current
$ ffmcp brain use mybrain

Chat Memory

# Add a message to memory
$ ffmcp brain memory add --role user --role-type user --content "Who was Octavia Butler?"

# Get memory context
$ ffmcp brain memory get

# Search memory
$ ffmcp brain memory search "Octavia"

# Clear memory
$ ffmcp brain memory clear

Named brains & sessions:

# Get memory for a specific brain
$ ffmcp brain memory get --brain mybrain

# Get memory for a specific session within a brain
$ ffmcp brain memory get --brain mybrain --session session-123

If --brain is omitted, the active brain is used. If --session is omitted, it defaults to the brain's default_session_id (if set) or the brain name. Both Zep and LEANN support the same memory operations.

Brains: Collections & Documents

Create a Collection

$ ffmcp brain collection create knowledge --description "KB for mybrain"

Add/Search/Delete Documents

$ ffmcp brain document add knowledge --text "Zep is a memory platform for LLM apps" --id doc1
$ ffmcp brain document search knowledge "memory platform"
$ ffmcp brain document delete knowledge --id doc1

Graph (Zep Cloud Only)

# Add JSON to user graph
$ echo '{"projects":{"alpha":{"status":"in progress"}}}' | ffmcp brain graph add user-123 --type json --input -

# Get graph
$ ffmcp brain graph get user-123

Note: Graph API is not available in LEANN backend. Use Zep Cloud backend for graph operations.

LEANN-Specific Operations

# Build a LEANN index directly from files/directories
$ ffmcp brain leann build my-index ./documents/ --backend hnsw

# List all LEANN indexes
$ ffmcp brain leann list

# Search a LEANN index directly
$ ffmcp brain leann search my-index "query text" --top-k 10

# Remove a LEANN index
$ ffmcp brain leann remove my-index --force

Real-World Examples

Example 1: Transcribe and Summarize a Meeting

# Step 1: Transcribe audio
$ ffmcp openai transcribe meeting.mp3 -o transcript.txt

# Step 2: Summarize transcript
$ ffmcp generate -i transcript.txt -o summary.txt -p openai

Example 2: Generate Image from Text Description

# Generate image
$ ffmcp openai image "A futuristic AI laboratory with holographic displays" -o image_url.txt

# Get the URL
$ cat image_url.txt

Example 3: Create Embeddings for Search

# Create embeddings for multiple documents
$ for file in *.txt; do
    ffmcp openai embed "$(cat $file)" -o "${file%.txt}_embedding.json"
done

Example 4: Batch Process Files

# Process all text files
$ for file in *.txt; do
    ffmcp generate -i "$file" -o "${file%.txt}_processed.txt" -p openai
done

Example 5: Complete Workflow

# 1. Transcribe audio
$ ffmcp openai transcribe meeting.mp3 -o transcript.txt

# 2. Summarize transcript
$ ffmcp generate -i transcript.txt -o summary.txt

# 3. Generate image based on summary
$ ffmcp openai image "$(cat summary.txt | head -c 100)"

# 4. Create embeddings for search
$ ffmcp openai embed "$(cat transcript.txt)" -o embeddings.json

Example 6: Interactive Script

#!/bin/bash
echo "Enter your prompt:"
read PROMPT
ffmcp generate "$PROMPT" -p openai -s

Example 7: Integration in Scripts

#!/bin/bash
RESULT=$(ffmcp generate "Translate to French: Hello world" -p openai)
echo "Translation: $RESULT"

Example 8: Agent Response to Speech

# 1. Create voice configuration
$ ffmcp voiceover create assistant-voice \
  --provider elevenlabs \
  --voice-id pNInz6obpgDQGcFmaJgB \
  --stability 0.6

# 2. Create agent with voice
$ ffmcp agent create assistant \
  -p openai -m gpt-4o-mini \
  -i "You are a helpful assistant" \
  --voice assistant-voice

# 3. Get agent response and convert to speech
$ response=$(ffmcp agent run "Explain quantum computing" --agent assistant)
$ ffmcp tts "$response" response.mp3 --voice assistant-voice

Example 9: Batch TTS Generation

# Generate audio for multiple text files
$ for file in *.txt; do
    ffmcp tts "$(cat $file)" "${file%.txt}.mp3" --voice narrator
done

Options Reference

Provider Selection

-p openai: Use OpenAI (default provider)
-p anthropic: Use Anthropic Claude

Model Selection

-m gpt-4o-mini: OpenAI default model (fast, cost-effective)
-m gpt-4o: More capable OpenAI model
-m claude-3-5-sonnet: Anthropic Claude model
-m dall-e-2: DALL·E 2 for image generation
-m tts-1-hd: High-quality text-to-speech model

Output Control

-o output.txt: Write output to file
-s: Stream response in real-time
--json: Output as JSON (for some commands)
--array: Output as array (for generate command)
-i input.txt: Read input from file

Generation Parameters

-t 0.7: Temperature (0.0-2.0) - Controls creativity/randomness
--max-tokens 500: Limit response length in tokens

Image Generation Options

--size 1024x1024: Image size (DALL·E 2 only: 256x256, 512x512, 1024x1024)
--quality hd: Image quality: standard or hd (DALL·E 3 only)
--style natural: Image style: natural or vivid (DALL·E 3 only)

Audio Options

-l es: Language hint for transcription (ISO 639-1 code)
-p "Context prompt": Prompt to help with transcription accuracy
-v nova: TTS voice: alloy, echo, fable, onyx, nova, shimmer
-s 1.2: TTS speed (0.25 to 4.0)

Embedding Options

-d 256: Custom embedding dimensions

Function Calling Options

-t tools.json: Path to JSON file containing tool definitions

TTS/Voiceover Options

--voice my-voice: Use saved voice configuration
--provider elevenlabs: TTS provider (elevenlabs, fishaudio)
--voice-id ID: Voice ID from provider (ElevenLabs)
--reference-id ID: Reference/voice model ID (FishAudio)
--reference-audio FILE: Path to reference audio file for voice cloning (FishAudio)
--stability 0.5: Voice stability (0.0-1.0, ElevenLabs)
--similarity-boost 0.75: Similarity to original voice (0.0-1.0, ElevenLabs)
--style 0.0: Style exaggeration (0.0-1.0, ElevenLabs)
--output-format mp3_44100_128: Audio output format (ElevenLabs)
--format mp3: Output format: mp3, wav, pcm, opus (FishAudio)
--prosody-speed 1.0: Speech speed multiplier (FishAudio)
--prosody-volume 0: Volume adjustment (FishAudio)

Troubleshooting

Common Issues

"Command not found": Make sure the virtual environment is activated: source venv/bin/activate
"API key not configured": Run ffmcp config -p openai -k YOUR_KEY or set environment variable
"Module not found": Install dependencies: pip install ffmcp[all] or pip install -e ".[all]" if installing from source
Permission errors: Ensure virtual environment is activated and you have write permissions
Import errors: Make sure you installed with provider extras: pip install ffmcp[openai] or pip install -e ".[openai]" if installing from source
"API key not configured for elevenlabs": Run ffmcp config -p elevenlabs -k YOUR_KEY or install package: pip install elevenlabs
"Unknown voice: my-voice": Check voice exists: ffmcp voiceover list or create it with ffmcp voiceover create
"Reference audio file not found" (FishAudio): Ensure reference audio file path is correct and file exists. Use high-quality audio (WAV, MP3, FLAC)

💡 Tips:

Always activate venv first: source venv/bin/activate
Use streaming (-s) for long responses to see progress
Save API keys in config: ffmcp config -p openai -k YOUR_KEY
Pipe commands together for complex workflows
Use -o flag to save outputs for later use
Check help for each command: ffmcp COMMAND --help

Getting Help

# General help
$ ffmcp --help

# Command-specific help
$ ffmcp generate --help
$ ffmcp openai --help
$ ffmcp openai image --help

# List providers
$ ffmcp providers

Table of Contents

Installation

Install via pip (Recommended)

Install with Specific Providers

Install via npm

Install from Source (Development)

Quick Start

1. Get API Keys

2. Configure API Keys

3. Test Basic Commands

Quick Reference: API Key Locations

Basic Commands

Text Generation

Simple Generation

With Provider and Model

Streaming Response

Control Creativity (Temperature)

Limit Response Length

With System Message

Output Formats

Read from File

Pipe Input

Advanced Options

Agents

Create an Agent

List, Use, Show

Run the Agent

Output Formats

Actions and Properties

Vision with Local Images

Hierarchical Teams

Create a Simple Team

Create a Team with Shared Brain

Create Nested Teams (Teams within Teams)

Run a Task with a Team

Output Formats

Manage Teams

How Hierarchical Teams Work

Example Hierarchical Structure

Chat Mode

Simple Chat

With System Message

Output Formats

OpenAI Features

🖼️ Image Generation (DALL·E)

👁️ Vision / Image Analysis

🎤 Audio Transcription (Whisper)

🌍 Audio Translation

🔊 Text-to-Speech

📊 Embeddings

🔧 Function Calling / Tools

🤖 Assistants API

🎙️ TTS/Voiceover

Quick Start

Voice Configuration Management

Create Voice Configuration

List and Manage Voices

Provider Voice Discovery

Text-to-Speech Generation

Using Saved Voice Configuration

Using Provider Directly

Voice Parameters Explained

Agent Voice Integration

Supported Providers

ElevenLabs

FishAudio

Advanced Usage

Batch TTS Generation

Voice Settings Experimentation

Integration with Agent Responses

Brains (Zep/LEANN Memory)

Setup Zep

Setup LEANN

Create and Use a Brain

Chat Memory

Brains: Collections & Documents

Create a Collection

Add/Search/Delete Documents

Graph (Zep Cloud Only)

LEANN-Specific Operations