search

fialr search <query> [options]

Search across file metadata using SQLite FTS5 full-text search, AI query expansion, or semantic vector similarity. Matches against filenames, entities, descriptors, tags, summaries, categories, and MIME types.

---

Arguments

Argument	Description
query	Search query (one or more words)

Options

Option	Description
--ai	Use AI to interpret the query and expand search terms
--semantic	Search by semantic similarity using vector embeddings
--similar FILE	Find files similar to the given file by embedding
--category CAT	Filter results by schema category
--sensitivity N	Filter by sensitivity tier (1, 2, or 3)
--limit N	Maximum results (default: 20)
--threshold N	Minimum similarity score, 0.0—1.0 (default: 0.0). Used with --similar.
--reindex	Rebuild the FTS5 search index from current data

---

What it does

Standard search

Without --ai, the query is passed directly to SQLite FTS5. FTS5 supports standard full-text operators:

• Space-separated words are AND-matched
• Quoted phrases match exactly
• OR combines alternatives
• * suffix matches word prefixes

Results are ranked by FTS5 relevance score and returned with file path, entity, descriptor, tags, category, and match score.

AI search

With --ai, the query is sent to the configured enrichment provider (Ollama by default, or cloud if configured). The provider interprets the natural-language query and extracts structured search terms, category filters, and date ranges. These are then used to build an FTS5 query.

AI search never sends file content to any provider — only the query text and metadata from search results. Tier gating applies to the query processing, not to file access.

Semantic search

With --semantic, the query is encoded into a vector embedding using the configured embedding model (Ollama by default). Files with semantically similar embeddings are returned ranked by cosine similarity.

Unlike --ai which expands search terms through LLM interpretation, semantic search directly embeds the query and compares it against file vectors computed during enrichment or via fialr embed.

Semantic search finds files by meaning. A query for “quarterly financial reports” matches files tagged “revenue summary” or “q1 earnings” because the embeddings capture semantic relationships that keyword search misses.

Requires embeddings to be computed first via fialr enrich --embed-only or during enrichment.

Similar file search

With --similar FILE, the embedding of the given file is compared against all other embeddings in the corpus using cosine similarity. Results are ranked by similarity score and returned with file metadata. This replaces the standalone fialr similar command, which remains available as a backward-compatible alias.

If the reference file does not have an embedding, run fialr enrich --embed-only first.

Search index

The FTS5 search index is populated automatically during enrichment. When fialr enrich processes a file, the enrichment results (entity, descriptor, tags, summary) are indexed alongside the file path and category.

Use --reindex to rebuild the index from current SQLite data if it becomes stale or after manual database changes.

---

Output

search "quarterly report"

  SEARCH    4 results
────────────────────────────────────────────────────────
  financial/2024-03-15-acme-quarterly_report.pdf
    entity  acme_corp
      tags  financial, quarterly, revenue
     score  0.94

  financial/2024-06-30-acme-quarterly_report.pdf
    entity  acme_corp
      tags  financial, quarterly
     score  0.91

  work/2024-01-15-acme-quarterly_review.pdf
    entity  acme
      tags  quarterly, review, performance
     score  0.78

  financial/2023-12-31-fidelity-quarterly_statement.pdf
    entity  fidelity
      tags  financial, quarterly, 401k
     score  0.72

---

Examples

# Basic full-text search
fialr search "invoice acme"

# Search with category filter
fialr search "receipt" --category financial

# Search Tier 1 files only
fialr search "passport" --sensitivity 1

# AI-enhanced natural language search
fialr search "tax documents from 2024" --ai

# Prefix matching
fialr search "quart*"

# Semantic search — find files by meaning
fialr search --semantic "quarterly financial reports from Q1"

# Find files similar to a specific file
fialr search --similar ~/Documents/contract.pdf

# Similar files with threshold
fialr search --similar ~/Documents/contract.pdf --limit 5 --threshold 0.8

# Rebuild the search index
fialr search --reindex

---

See also

• enrich — populate metadata for search and compute embeddings
• Enrichment guide — how metadata enters the search index
• Search guide — search workflows and strategies
• scan — sensitivity tiers used for filtering