Skip to main content
RCLI uses a simple file-based configuration system with sensible defaults for macOS.

​
Directory Structure

~/Library/RCLI/
├── models/              # AI models (LLM, STT, TTS, VAD)
├── index/               # RAG vector index and BM25 data
└── config               # Active model selection

​
Environment Variables

​
HOME
string
required
User home directory (macOS standard).RCLI uses $HOME to locate default directories:
  • Models: $HOME/Library/RCLI/models
  • Index: $HOME/Library/RCLI/index
  • Config: $HOME/Library/RCLI/config
​
RCLI_ROOT
string
Override RCLI installation root (for development builds).
export RCLI_ROOT=/path/to/rcli/source
rcli setup
Used by rcli setup to locate the scripts/download_models.sh script in development environments.
​
COLORFGBG
string
Terminal color scheme detection.RCLI reads $COLORFGBG to detect dark/light terminal backgrounds and adjusts TUI theme automatically.Set by most modern terminals (iTerm2, Terminal.app, etc.).

​
Configuration File

​
~/Library/RCLI/config
file
Plain text config file storing active model selections.Format:
llm_model=lfm2-1.2b-tool-q4_k_m
stt_model=whisper-base.en
tts_model=piper-lessac-medium
Managed by:
  • rcli models - Interactive model picker
  • rcli upgrade-llm - LLM upgrade wizard
  • rcli upgrade-stt - STT upgrade wizard
  • rcli voices - TTS voice picker
Changes persist across RCLI sessions.

​
Model Storage

​
~/Library/RCLI/models
directory
AI models directory.Default location for all models. Override with --models flag:
rcli --models /path/to/models
Total size: ~1-5 GB depending on installed models.
​
LLM Models
.gguf
  • lfm2-1.2b-tool-q4_k_m.gguf (731 MB, default)
  • lfm2-350m-q4_k_m.gguf (219 MB)
  • lfm2.5-1.2b-instruct-q4_k_m.gguf (731 MB)
  • lfm2-2.6b-q4_k_m.gguf (1.5 GB)
  • qwen3-0.6b-q4_k_m.gguf (456 MB)
  • qwen3.5-0.8b-q4_k_m.gguf (600 MB)
  • qwen3.5-2b-q4_k_m.gguf (1.2 GB)
  • qwen3-4b-q4_k_m.gguf (2.5 GB)
  • qwen3.5-4b-q4_k_m.gguf (2.7 GB)
​
STT Models
.onnx
Zipformer (streaming):
  • sherpa-onnx-streaming-zipformer-en-2023-06-26/*.onnx (50 MB total)
Whisper (offline):
  • whisper-base.en-encoder.onnx (140 MB)
  • whisper-base.en-decoder.onnx
Parakeet TDT (high accuracy):
  • parakeet-tdt-0.6b-v3/*.onnx (640 MB)
​
TTS Voices
.onnx
  • piper-en_US-lessac-medium.onnx (60 MB, default)
  • piper-en_US-amy-medium.onnx (60 MB)
  • kitten-tts-nano-0.8.onnx (90 MB, 8 speakers)
  • matcha-ljspeech.onnx (100 MB)
  • kokoro-en-v0.19.onnx (310 MB, 11 speakers)
  • kokoro-multi-v1.1.onnx (500 MB, 103 speakers)
​
VAD
.onnx
  • silero_vad.onnx (0.6 MB)
​
Embeddings
.gguf
  • snowflake-arctic-embed-s-q8_0.gguf (34 MB)

​
RAG Index

​
~/Library/RCLI/index
directory
RAG vector index and metadata.Created by:
rcli rag ingest ~/Documents/notes
Loaded by:
rcli --rag ~/Library/RCLI/index
rcli ask --rag ~/Library/RCLI/index "your question"
Contents:
  • vector.usearch - HNSW vector index (USearch)
  • bm25.bin - BM25 full-text index
  • chunks.json - Document chunks and metadata
  • manifest.json - Index configuration
Size: Varies by corpus (typically 10-100 MB per 1000 documents)

​
Action Preferences

​
~/.rcli/actions.json
file
Action enable/disable preferences.Format:
{
  "open_app": true,
  "quit_app": true,
  "send_message": false,
  "search_web": true
}
Managed by:
  • TUI Actions panel (press A)
  • rcli_set_action_enabled() API
Preferences persist across sessions. Disabled actions are hidden from the LLM’s tool definitions.

​
Permissions

​
Microphone Access
macOS permission
Required for rcli listen and interactive push-to-talk.Location: System Settings → Privacy & Security → MicrophoneEnable for your terminal app (Terminal.app, iTerm2, or Cursor).RCLI automatically requests permission on first voice command.
​
Accessibility
macOS permission
Required for some actions (window management, app control).Location: System Settings → Privacy & Security → AccessibilityEnable if actions like fullscreen_window or close_window fail.

​
Temporary Files

​
/tmp/rcli_tts_*.wav
temporary
TTS audio output files.RCLI synthesizes TTS to temp WAV files, plays via afplay, then deletes after playback.Files are cleaned up automatically unless RCLI is force-killed.

​
Cleanup

# Delete all models and config
rm -rf ~/Library/RCLI
rm -rf ~/.rcli

​
Migration

To move RCLI to a different models directory: 
# Copy models to new location
cp -r ~/Library/RCLI/models /path/to/new/location

# Use --models flag
rcli --models /path/to/new/location

# Or set as default (edit config manually)
echo "models_dir=/path/to/new/location" >> ~/Library/RCLI/config

​
Disk Space

Default rcli setup downloads:
  • LFM2 1.2B LLM (731 MB)
  • Whisper base.en (140 MB)
  • Zipformer streaming STT (50 MB)
  • Piper Lessac TTS (60 MB)
  • Silero VAD (0.6 MB)
  • Snowflake embeddings (34 MB)
Total: ~1 GB
All models downloaded:
  • 9 LLM models (456 MB - 2.7 GB each)
  • 3 STT models (50 MB - 640 MB)
  • 6 TTS voices (60 MB - 500 MB)
  • VAD + embeddings (35 MB)
Total: ~5 GB
Index size depends on:
  • Number of documents
  • Document size
  • Chunk size (default 512 tokens)
Typical: 50 MB per 1000 documents

​
Troubleshooting

# Verify models directory
ls ~/Library/RCLI/models

# Re-download defaults
rcli setup

# Check custom path
rcli --models ~/custom-models info

# Delete and rebuild
rm -rf ~/Library/RCLI/index
rcli rag ingest ~/Documents/notes

# Delete config to reset to defaults
rm ~/Library/RCLI/config

# Next run will auto-detect best models
rcli info

Commands

Complete command reference

Options

Command-line flags and parameters

Build docs developers (and LLMs) love

Get started for freeTalk to us