Skip to main content

​
Overview

The search command performs semantic search across all indexed documents. It supports multiple search modes including dense vector search, BM25 lexical search, and hybrid approaches.
You can search directly without the search keyword: know "your query" is equivalent to know search "your query"

​
Syntax

know search <query> [OPTIONS]
know <query> [OPTIONS]  # Direct query

​
Parameters

​
query
string
required
The search query. Natural language questions and semantic queries work best.

​
Options

​
--limit
integer
default:"5"
Number of results to return.Alias: -n
​
--glob
list[string]
Include only files matching glob patterns. Can be specified multiple times or as comma-separated values.Alias: -gExample: --glob "**/*.md" --glob "notes/**"
​
--since
string
Only include files modified since the specified time. Accepts relative time (e.g., 7d, 12h, 30m) or absolute dates (e.g., 2024-01-15).Examples:
  • 7d - Last 7 days
  • 12h - Last 12 hours
  • 30m - Last 30 minutes
  • 2w - Last 2 weeks
  • 2024-01-15 - Since January 15, 2024
​
--bm25
boolean
default:"false"
Use BM25 lexical search instead of semantic vector search. Better for exact keyword matches.
​
--hybrid
boolean
default:"false"
Use hybrid search combining BM25 and vector search. Balances semantic understanding with keyword matching.
​
--benchmark
boolean
default:"false"
Show both dense and BM25 results side-by-side for comparison.
​
--plain
boolean
default:"false"
Render results as plain text instead of rich formatted output.
​
--json
boolean
default:"false"
Render results as JSON to stdout.
​
--json-out
Path
Write JSON results to the specified file.

​
Search Modes

​
Dense Vector Search (default)

Uses semantic embeddings to find conceptually similar content, even if exact keywords don’t match. 
know "how to configure authentication"
Uses traditional keyword-based ranking (BM25 algorithm). Better for finding exact terms. 
know "API_KEY" --bm25
Combines both approaches for balanced results. 
know "database connection" --hybrid

​
Examples

know "python async functions"

╭─────────────────────────────────────────────────────╮
│ Results for: python async functions                │
├─────────────────────────────────────────────────────┤
│ 1. /home/user/notes/async-guide.md:45              │
│    Score: 0.87                                      │
│    Async functions in Python use the async/await...│
│                                                     │
│ 2. /home/user/docs/python-concurrency.txt:123     │
│    Score: 0.82                                      │
│    To define an async function, use the async...   │
╰─────────────────────────────────────────────────────╯

​
Direct query (without ‘search’ keyword)

know "what is semantic search"

​
Limit results

know "docker compose" --limit 10

​
Filter by glob pattern

know "configuration" --glob "**/*.yaml" --glob "**/*.yml"

​
Search recent files only

know "bug fix" --since 7d

​
BM25 search for exact keywords

know "TODO: FIXME" --bm25

​
Hybrid search

know "error handling" --hybrid --limit 10

​
Compare search modes

know "authentication" --benchmark

╭─────────────────────────────────────────────────────╮
│ Dense Vector Results                                │
├─────────────────────────────────────────────────────┤
│ ... results ...                                     │
╰─────────────────────────────────────────────────────╯

╭─────────────────────────────────────────────────────╮
│ BM25 Results                                        │
├─────────────────────────────────────────────────────┤
│ ... results ...                                     │
╰─────────────────────────────────────────────────────╯

​
Plain text output

know "API documentation" --plain

​
JSON output to stdout

know "database schema" --json

{
  "query": "database schema",
  "results": [
    {
      "file": "/home/user/docs/schema.md",
      "line": 23,
      "score": 0.89,
      "content": "..."
    }
  ]
}

​
Save results to file

know "migration guide" --json-out results.json

​
Complex query with multiple filters

know "kubernetes deployment" \
  --limit 15 \
  --glob "**/*.md" \
  --since 30d \
  --hybrid
For conceptual queries like “how to…” or “what is…”, use the default dense vector search. For finding specific variable names, error codes, or exact phrases, use --bm25.
You cannot use both --bm25 and --hybrid together. Choose one search mode.
You cannot use both --plain and --json together. Choose one output format.

​
Time Format Reference

The --since flag accepts flexible time formats:
FormatDescriptionExample
<N>mMinutes ago30m
<N>hHours ago12h
<N>dDays ago7d
<N>wWeeks ago2w
YYYY-MM-DDAbsolute date2024-01-15
ISO 8601Full timestamp2024-01-15T10:30:00

​
Prerequisites

Before searching, you must:
  1. Add directories: know add <directory>
  2. Index content: know index

​
See Also

  • know index - Index directories
  • know add - Add directories to watch list

Build docs developers (and LLMs) love

Get started for freeTalk to us