vexor 0.5.0

A vector-powered CLI for semantic search over files.

Vexor

---

Vexor is a vector-powered CLI for semantic file search. It supports configurable remote embedding models and ranks results by cosine similarity.

Install

Download from releases without python, or with:

pip install vexor # or use pipx, uv

The CLI entry point is vexor.

Configure

Set the Gemini API key once and reuse it everywhere:

vexor config --set-api-key "YOUR_KEY"

Optional defaults:

vexor config --set-model gemini-embedding-001
vexor config --set-batch-size 0   # 0 = single request
vexor config --set-provider gemini
vexor config --set-base-url https://proxy.example.com  # optional proxy; use --clear-base-url to reset

Provider defaults to gemini, so you only need to override it when switching to upcoming backends (e.g., openai). Base URLs are optional and let you route requests through a custom proxy; run vexor config --clear-base-url to return to the official endpoint.

Environment/API keys can be supplied via vexor config --set-api-key, VEXOR_API_KEY, or provider-specific variables (GOOGLE_GENAI_API_KEY, OPENAI_API_KEY). Example OpenAI setup:

vexor config --set-provider openai
vexor config --set-model text-embedding-3-small
export OPENAI_API_KEY="sk-..."   # or use vexor config --set-api-key

Configuration is stored in ~/.vexor/config.json.

Inspect or reset every cached index:

vexor config --show-index-all
vexor config --clear-index-all

Workflow

1. Index the project root (includes every subdirectory):

   vexor index --path ~/projects/demo --mode name --include-hidden
   

2. Search from anywhere, pointing to the same path:

   vexor search "api client config" --path ~/projects/demo --mode name --top 5
   

   Output example:

   Vexor semantic file search results
   ──────────────────────────────────
   #   Similarity   File path                      Preview
   1   0.923        ./src/config_loader.py        config loader entrypoint
   2   0.871        ./src/utils/config_parse.py   parse config helpers
   3   0.809        ./tests/test_config_loader.py tests for config loader
   

Tips:

• Keep one index per project root; subdirectories need separate indexes only if you explicitly run vexor index on them.
• Toggle --no-recursive (or -n) on both index and search when you only care about the current directory; recursive and non-recursive caches are stored separately.
• Hidden files are included only if both index and search use --include-hidden.
• Re-running vexor index only re-embeds files whose names changed (or were added/removed); if more than half the files differ, it automatically falls back to a full rebuild for consistency.
• Specify the indexing mode with --mode; currently name (file names only) and head (first chunk of supported text/code/PDF/DOCX/etc. files) are available, each with its own cache.
• Switch embedding providers (Gemini by default, OpenAI supported) via vexor config --set-provider PROVIDER and pick a matching embedding model.

Commands

Command	Description
vexor index --path PATH --mode MODE [--include-hidden] [--no-recursive] [--clear/--show]	Scans PATH (recursively by default), embeds content according to MODE (name or head), and writes a cache under ~/.vexor.
vexor search QUERY --path PATH --mode MODE [--top K] [--include-hidden] [--no-recursive]	Loads the cached embeddings for PATH (matching the chosen mode/recursion/hidden settings), shows matches for QUERY.
vexor doctor	Checks whether the vexor command is available on the current PATH.
vexor update	Fetches the latest release version and shows links to update via GitHub or PyPI.
vexor config --set-api-key/--clear-api-key	Manage the stored API key (Gemini by default).
vexor config --set-model/--set-batch-size/--show	Manage default model, batch size, and inspect current settings.
vexor config --set-provider/--set-base-url/--clear-base-url	Switch embedding providers and optionally override the remote base URL.
vexor config --show-index-all/--clear-index-all	Inspect or delete every cached index regardless of path/mode.

Documentation

See the docs for more details.

Contributions, issues, and PRs are all welcome!

Star this repo if you find it helpful!

License

This project is licensed under the MIT License.