Quickstart

Get Sercha up and running in 5 minutes. This guide walks you through installing Sercha, indexing your first documents, and running your first search.

Installation

macOS

brew tap custodia-labs/sercha
brew install sercha

First Run on macOS

macOS may block the binary on first run. If you see "killed", run:

xattr -d com.apple.quarantine $(which sercha)

Ubuntu / Debian

curl -1sLf 'https://dl.cloudsmith.io/public/custodia-labs/sercha/setup.deb.sh' | sudo bash
sudo apt-get install -y sercha

RHEL / CentOS / Fedora

curl -1sLf 'https://dl.cloudsmith.io/public/custodia-labs/sercha/setup.rpm.sh' | sudo bash
sudo yum install -y sercha

Binary Download

Download from GitHub Releases:

Platform	File
macOS (Apple Silicon)	sercha_*_darwin_arm64.tar.gz
Linux (x86_64)	sercha_*_linux_amd64.tar.gz
Linux (ARM64)	sercha_*_linux_arm64.tar.gz

Xapian Required

Binary downloads require Xapian to be installed:

• macOS: brew install xapian
• Ubuntu/Debian: sudo apt install libxapian30
• RHEL/CentOS: sudo yum install xapian-core-libs

tar -xzf sercha_*.tar.gz
sudo mv sercha /usr/local/bin/

Verify Installation

sercha version

Step 1: Add Your First Source

Let's index a local folder. This is the simplest way to get started.

Command Line

sercha source add filesystem -c path=~/Documents

Interactive Wizard

sercha source add

The wizard guides you through:

1. Selecting a connector type
2. Configuring source-specific options
3. Setting up authentication (if required)

You should see:

Source created: <source-id>
  Type: filesystem
  Name: ~/Documents

Step 2: Sync Documents

Now sync the source to index your documents:

sercha sync

Sercha will scan the folder, normalise documents (PDF, Markdown, plain text, etc.), and build the search index.

Syncing source: <source-id>
  Processed: 127 documents
  Indexed: 127 documents
  Duration: 3.2s

Sync a Specific Source

To sync only one source, pass its ID:

sercha sync <source-id>

Step 3: Search

Search your indexed documents:

sercha search "meeting notes"

Results show matching documents with relevance scores:

Found 5 results:

  1. ~/Documents/work/meeting-notes-2024-01.md
     Score: 0.92
     ...discussed Q1 planning and project timelines...

  2. ~/Documents/projects/standup-notes.txt
     Score: 0.78
     ...weekly meeting notes for the team...

Step 4: Launch the TUI

For an interactive experience, launch the Terminal UI:

sercha tui

The TUI provides:

• Real-time search as you type
• Keyboard navigation (j/k or arrows)
• Document preview and actions
• Source management

Keyboard Shortcuts

Key	Action
?	Show help
q	Quit
Enter	Select/execute
Esc	Go back
j/k	Navigate up/down

Next Steps

Add More Sources

GitHub (PAT)

sercha source add github --token ghp_your_token -c content_types=files,issues

Getting a GitHub Token

Create a Personal Access Token at github.com/settings/tokens with repo scope.

GitHub (OAuth)

# First, create an OAuth app configuration
sercha auth add --provider github

# Then add the source using the OAuth app
sercha source add github --auth <auth-id> -c content_types=files,issues

Google Services

# Use the interactive wizard for Google OAuth setup
sercha source add
# Select: google-drive, gmail, or google-calendar

See Supported Connectors for all options.

Enable AI-Powered Search

Sercha supports semantic search and LLM-assisted query expansion. Configure AI providers with the settings wizard:

sercha settings wizard

OpenAI (Recommended)

Cloud-based, requires API key from platform.openai.com.

1. Run sercha settings wizard
2. Select OpenAI as embedding and/or LLM provider
3. Enter your API key when prompted

Ollama (Local)

Free, private, runs entirely on your machine.

1. Install Ollama
2. Pull a model: ollama pull nomic-embed-text
3. Run sercha settings wizard and select Ollama

Anthropic

LLM only (no embeddings). Requires API key from console.anthropic.com.

1. Run sercha settings wizard
2. Select Anthropic as LLM provider
3. Enter your API key when prompted

See AI Models for details on hybrid and AI-assisted search.

Learn More

• Basic Configuration - Configure paths, settings, and defaults
• Commands Reference - Full CLI command documentation
• TUI Guide - Master the terminal interface
• Architecture - Understand how Sercha works