Doc

Full-text search across local documentation files — without leaving the terminal.

annave doc search builds an inverted index over a local directory tree and runs full-text search with prefix matching and relevance scoring. Results can be opened directly in your editor.

Usage

bash

annave doc search [query] [flags]

Flags

Flag	Short	Default	Description
--path	-p	.	Root directory to index and search
--format		plain	Output format: plain, json, table
--open		false	Open the top result in $EDITOR
--ext		—	File extensions to include (repeatable). Default covers common doc formats.

Default extensions: .md, .mdx, .txt, .rst, .html, .yaml, .json.

Examples

Search current directory

bash

annave doc search "rate limiting"

Search a specific path

bash

annave doc search "authentication" --path ./docs

Open top result in editor

bash

annave doc search "deployment" --open

Search only Markdown files

bash

annave doc search "rollback" --ext .md

Multiple extensions

bash

annave doc search "timeout" --ext .md --ext .yaml

Editor integration

--open is line-aware for the following editors — it opens the file at the matched line:

Editor	Opened as
nvim / vim	`nvim +{line} {file}`
VS Code (code)	`code --goto {file}:{line}`
nano	`nano +{line} {file}`
Any other $EDITOR	File only — no line argument

If $EDITOR is not set, the file is opened using the OS default application (open on macOS, xdg-open on Linux).

Plain output

text

  Doc search — "rate limiting"  (3 result(s))

  [1] docs/api-reference.md
       API Reference
       ...requests exceeding the rate limit receive a 429 response...
       line 87     score 1.0  md

  [2] docs/configuration.md
       Configuration Guide
       ...rate_limit.requests_per_minute controls the per-IP bucket...
       line 142    score 0.5  md

JSON output shape

json

[
  {
    "file": {
      "path": "/absolute/path/docs/api-reference.md",
      "rel_path": "docs/api-reference.md",
      "title": "API Reference",
      "format": "md",
      "size_bytes": 14200,
      "mod_time": "2026-05-14T09:00:00Z"
    },
    "line": 87,
    "score": 1.0,
    "excerpt": "...requests exceeding the rate limit receive a 429 response..."
  }
]

What to watch

Multiple query words are treated as AND terms — all words must appear in the file to match.
Files over 10 MB are skipped during indexing. Change doc.max_file_size_mb in limits.yaml to raise this.
The index is built on each run — there is no persistent cache. On very large directories (tens of thousands of files), the first run takes a few seconds.
Hidden directories (starting with .) and known toolchain directories (node_modules, vendor, .git, dist) are skipped automatically.
Maximum directory depth is 10 by default. Change doc.max_depth in limits.yaml if your documentation is nested deeper.