Skip to main content
This guide assumes you’ve already installed RCLI. If not, run:
curl -fsSL https://raw.githubusercontent.com/RunanywhereAI/RCLI/main/install.sh | bash

​
Your First Voice Command

Let’s get RCLI running and execute your first voice command in three steps.
1

Launch Interactive Mode

Start the RCLI TUI (terminal user interface):
rcli
You’ll see a dashboard with:
  • Conversation history panel
  • Live hardware metrics (CPU, GPU, RAM usage)
  • Active models (LLM, STT, TTS)
  • Keyboard shortcuts guide
2

Press and Hold SPACE to Record

Hold down the SPACE bar and speak a command:
“What’s the weather like today?”
Release SPACE when done. You’ll see:
  1. STT: Your speech transcribed to text (~40ms latency)
  2. LLM: Response generated token-by-token (~160 tok/s)
  3. TTS: Audio synthesis and playback (~150ms)
3

Hear the Response

RCLI speaks the answer through your Mac’s speakers. The entire pipeline (voice-in → audio-out) completes in ~130ms on Apple M3 Max.
On first run, macOS will prompt for microphone permissions. Click OK to grant access. Without microphone access, voice commands won’t work.

​
Try macOS Actions

RCLI ships with 43 macOS actions for controlling your system by voice. Try these examples: 
# In the TUI, press SPACE and say:
"Open Safari"
"Launch Spotify"
"Open System Settings"

​
View All Actions

List all 43 available actions: 
rcli actions
Get details on a specific action: 
rcli actions open_app
Output: 
{
  "name": "open_app",
  "description": "Open an application by name",
  "category": "system",
  "parameters": {
    "app_name": "string (required) - Name of the application to open"
  },
  "examples": [
    "Open Safari",
    "Launch Spotify",
    "Open Terminal"
  ]
}

​
Text Commands (No Voice)

RCLI also accepts text input. Use rcli ask for one-shot commands without voice: 
rcli ask "open Safari"
rcli ask "create a note called Ideas"
rcli ask "what's 15% of 240?"
Text commands skip STT and TTS, executing only the LLM + action pipeline.

​
Type in the TUI

In interactive mode (rcli), you can also type text directly. Just start typing (no need to press a key):
  1. Launch rcli
  2. Type: what time is it?
  3. Press Enter
RCLI processes the text and responds via TTS.

​
Continuous Voice Mode

For hands-free control, use listen mode (always-on voice detection): 
rcli listen
RCLI continuously monitors your microphone using VAD (voice activity detection). Speak naturally without pressing any keys:
“Hey RCLI, what’s the time?”
“Open Spotify and play some music”
“Create a reminder to buy milk”
Press ESC to stop listening mode.
Listen mode is always listening. It’s more convenient than push-to-talk but uses more CPU/GPU. Recommended for Apple M2 or later.

​
Interactive TUI Controls

The RCLI TUI (rcli command) supports several keyboard shortcuts:
KeyAction
SPACEStart/stop push-to-talk recording
MModels panel — browse, download, switch LLM/STT/TTS
AActions panel — view, enable/disable, test actions
BBenchmarks panel — run STT, LLM, TTS, E2E benchmarks
RRAG panel — ingest documents, clear index
DCleanup panel — delete unused models
TToggle tool call trace (see LLM tool calls inline)
ESCStop processing / close panel / quit

​
Tool Call Trace

Press T to enable tool call tracing. When active, every LLM tool call is displayed inline: 
> open Safari
  ~ [TRACE] Tool call: open_app({"app_name": "Safari"})
  ~ [TRACE] open_app -> OK: {"success": true, "output": "Opened Safari"}
  RCLI: Done! Safari is now open.
This is useful for debugging and understanding how the LLM routes your requests.

​
Query Local Documents (RAG)

RCLI includes a hybrid RAG system (vector + BM25 search) for querying local documents.
1

Ingest Documents

Index a directory of files (PDF, DOCX, TXT):
rcli rag ingest ~/Documents/notes
RCLI processes each file, chunks the content, and builds a vector index (~4ms retrieval latency).
2

Query by Voice or Text

Ask questions about your documents:
rcli ask --rag ~/Library/RCLI/index "summarize the meeting notes from last week"
Or in the TUI, press SPACE and say:
“What were the key decisions in the project plan?”
3

Drag and Drop (TUI Only)

In interactive mode (rcli), drag a file or folder from Finder into the terminal window. RCLI auto-indexes it and you can immediately ask questions.

​
Check RAG Index Status

rcli rag status
Output: 
RAG Index: ~/Library/RCLI/index
Documents: 42
Chunks: 1,247
Index size: 12.3 MB
Retrieval latency: ~4ms (avg)

​
Clear the Index

rcli rag clear
This deletes the vector index and frees disk space.

​
Model Management

RCLI supports 20+ models across LLM, STT, and TTS. Switch models without restarting: 
rcli models
# Opens TUI with tabs for LLM, STT, TTS
# Navigate with arrow keys, press Enter to download/switch

​
Model Storage

All models are stored in ~/Library/RCLI/models/. Active model selection persists in ~/Library/RCLI/config. Free up space by removing unused models: 
rcli cleanup

​
Benchmarking

RCLI includes a built-in benchmark suite for measuring STT, LLM, TTS, and end-to-end latency. 
rcli bench
Output (Apple M3 Max example): 
====================================
RCLI Benchmarks
====================================

STT (Whisper base.en):
  Avg latency: 43.7 ms
  Real-time factor: 0.022x

LLM (LFM2 1.2B Tool Q4_K_M):
  Time to first token: 22.5 ms
  Generation throughput: 159.6 tok/s

TTS (Piper Lessac):
  Avg latency: 150.6 ms

RAG (Hybrid Retrieval):
  Query latency: 3.82 ms

E2E (Voice-in to Audio-out):
  Total latency: 131 ms

====================================

​
Run Specific Benchmark Suites

rcli bench --suite llm
Available suites: stt, llm, tts, e2e, tools, rag, memory, all.

​
Common Workflows

​
Workflow 1: Voice-Controlled Music

# Launch RCLI
rcli

# Press SPACE and say:
"Open Spotify"
"Play some jazz"
"Set volume to 60"
"Next track"
"Pause"

​
Workflow 2: Document Intelligence

# Index your documents
rcli rag ingest ~/Documents/work

# Query them by voice
rcli listen
# Then say: "What were the action items from the Q4 planning doc?"

​
Workflow 3: System Automation

# Chain multiple actions
rcli ask "lock the screen"
rcli ask "take a screenshot"
rcli ask "open Terminal and set dark mode"

​
Workflow 4: Model Experimentation

# Compare LLMs on the same query
rcli models  # Switch to Qwen3.5 2B
rcli ask "explain quantum computing"

rcli models  # Switch to LFM2 2.6B
rcli ask "explain quantum computing"

# Benchmark both
rcli bench --all-llm --suite llm

​
Next Steps

You’ve learned the basics of RCLI. Explore these topics next:

Commands Overview

Deep dive into all RCLI commands and options

macOS Actions

Master all 43 system actions

Model Guide

Learn about 20+ supported AI models

Architecture

Understand the voice pipeline internals

​
Troubleshooting

  1. Check system volume (not muted)
  2. Verify TTS model is installed: rcli info
  3. Test TTS directly: rcli ask --no-speak "hello" (should show text output)
  4. Re-download TTS model: rcli voices
  1. Grant microphone permissions (System Settings → Privacy & Security → Microphone)
  2. Test microphone: rcli mic-test (should show audio levels)
  3. Speak louder or closer to the microphone
  4. Check VAD model: rcli info (Silero VAD should be listed)
  1. Check action status: rcli actions
  2. Test action directly: rcli action open_app '{"app_name": "Safari"}'
  3. Enable the action if disabled: In the TUI, press A → navigate to action → toggle on
  4. Check macOS permissions (some actions require Accessibility access)
  1. Check hardware: rcli info (ensure Metal GPU is detected)
  2. Switch to a smaller/faster LLM: rcli upgrade-llm → Qwen3 0.6B (~250 tok/s)
  3. Close other GPU-intensive apps
  4. Benchmark your system: rcli bench

Need Help?

View the full troubleshooting guide for advanced issues

Build docs developers (and LLMs) love

Get started for freeTalk to us