---
source: src/main.rs
expression: sub.render_long_help().to_string()
---
Search stored messages.

`--mode vector` (default) matches on meaning; `--mode fts` matches exact whole words (BM25). Keep the query about concepts; scope with `--project`, `--from-date`, and friends instead of putting names in the query.

Usage: pond search [OPTIONS] <QUERY>

Arguments:
  <QUERY>
          Free-text query. Semantic concepts work best; project names belong in `--project`

Options:
      --namespace <NAMESPACE>
          Tenant namespace. The personal pond has exactly one; leave at the default
          
          [default: local]

      --limit <LIMIT>
          Max sessions to return
          
          [default: 10]

      --mode <MODE>
          Retrieval arm: `vector` (default - matches on meaning) or `fts` (exact whole words, BM25). Falls back to `fts` when the store has no embeddings
          
          [possible values: fts, vector]

      --sort-by <SORT_BY>
          Result order: `relevance` (default) or `recency` (newest first)
          
          [possible values: relevance, recency]

      --project <PROJECT>
          Project filter: substring match by default.
          
          `--project pond` -> contains "pond". Prefix with `re:` for regex (`--project 're:^/Users/.*/x402'`); `lit:` escapes a literal value that would otherwise be parsed as a prefix.

      --session-id <ID>
          Filter to one session (exact match) - search within a single, possibly long, session

      --from-date <FROM_DATE>
          ISO date (YYYY-MM-DD) lower bound, inclusive

      --to-date <TO_DATE>
          ISO date (YYYY-MM-DD) upper bound, inclusive

      --min-score <MIN_SCORE>
          Score floor on raw cosine (vector mode only); hits below it are dropped. Rejected in fts mode (BM25 is unbounded). Not an absence signal - present and absent content score in overlapping bands, so leave at 0 unless trimming an over-long tail
          
          [default: 0]

      --explain
          Print Lance query plans instead of search results

      --format <FORMAT>
          Output format: `text` (readable transcript) or `json` (one document)
          
          [default: text]
          [possible values: text, json]

  -h, --help
          Print help (see a summary with '-h')

Global options:
      --storage-path <URL>
          Storage destination: a local path or remote URL.
          
          Accepts a bare path, `~/path`, `file://`, `s3://bucket/prefix`, `s3+https://host/bucket/prefix`, `gs://`, `az://`, or the keyword `local` (the platform default local data dir). Default: `[storage].path` from config, then the platform data dir (`~/.local/share/pond`).
          
          [env: POND_STORAGE_PATH]

      --config-file <PATH>
          Config file to read (default: `~/.config/pond/config.toml`)
          
          [env: POND_CONFIG_FILE]

  -v, --verbose...
          Increase logging verbosity

  -q, --quiet...
          Decrease logging verbosity

Examples:
  pond search "lance compaction tuning"
  pond search "auth retry" --project pond --limit 5
  pond search "merge_insert" --mode fts --sort-by recency
  pond search "migration plan" --from-date 2026-05-01 --format json
