Building a Search System for CLI Commands

One of the core features of CLI Compass is the ability to quickly find the right command when you need it. In this post, I'll walk through how I designed and implemented the search system.

The Problem

As developers, we accumulate hundreds of CLI commands across different tools. Finding the right command when you need it—especially under pressure—can be frustrating. I wanted CLI Compass to make this as fast as possible.

Choosing Supabase for Search

I chose Supabase as the backend because it provides:

• Full-text search out of the box via PostgreSQL's tsvector and tsquery
• Real-time subscriptions so the UI stays in sync
• Row-level security to keep user data private

Implementation

The search system works in three layers:

1. Indexing

When a user saves a new command, we generate a search vector that includes the command name, description, and tags:

CREATE INDEX commands_search_idx ON commands
USING gin(to_tsvector('english', name || ' ' || description || ' ' || tags));

2. Query Processing

User queries are normalized and converted to tsquery format. We support both exact phrase matching and fuzzy matching to handle typos.

3. Ranking

Results are ranked by relevance using ts_rank, with a boost for exact matches in the command name field.

Lessons Learned

• Keep it simple: PostgreSQL's built-in search was more than enough—no need for Elasticsearch
• Tag-based filtering complements full-text search nicely for narrowing results
• Debouncing the search input improved perceived performance significantly

What's Next

I'm exploring adding semantic search using embeddings so users can search by intent rather than exact keywords—for example, searching "how to list running containers" would match docker ps.