Vexor CLI Skill

Goal

Find files by intent (what they do), not exact text.

Use It Like This

• Use vexor first for intent-based file discovery.
• If vexor is missing, follow references/install-vexor.md.

Command

vexor "<QUERY>" [--path <ROOT>] [--mode <MODE>] [--ext .py,.md] [--exclude-pattern <PATTERN>] [--top 5] [--format rich|porcelain|porcelain-z]

Common Flags

• --path/-p: root directory (default: current dir)
• --mode/-m: indexing/search strategy
• --ext/-e: limit file extensions (e.g., .py,.md)
• --exclude-pattern: exclude paths by gitignore-style pattern (repeatable; .js → **/*.js)
• --top/-k: number of results
• --include-hidden: include dotfiles
• --no-respect-gitignore: include ignored files
• .vexorignore project rules always apply, even with --no-respect-gitignore.
• --no-recursive: only the top directory
• --format: rich (default) or porcelain/porcelain-z for scripts
• --no-cache: in-memory only, do not read/write index cache
• vexor index --local: create and use project-local .vexor/index.db storage

Project Config

• The nearest .vexor/config.json applies automatically for the resolved
  search or index path.
• It accepts only rerank, auto_index, model, embedding_dimensions,
  batch_size, embed_concurrency, and extract_concurrency.
• batch_size must be at least 0; both concurrency values must be at least
  1.
• Credentials and endpoints (api_key, base_url, remote_rerank) and all
  other fields are rejected.
• Precedence is global config, project config, environment overrides, then
  explicit arguments.
• vexor config --show labels each field's origin and vexor doctor lists
  active overrides; mutating vexor config commands remain global-only.

Modes (pick the cheapest that works)

• auto: routes by file type (default)
• name: filename-only (fastest)
• head: first lines only (fast)
• brief: keyword summary (good for PRDs)
• code: code-aware chunking for .py/.js/.ts (best default for codebases)
• outline: Markdown headings/sections (best for docs)
• full: chunk full file contents (slowest, highest recall)

Troubleshooting

• Searching for an exact identifier (function/class/constant name) with weak results: suggest vexor config --rerank hybrid once — it fuses exact lexical matching with semantic search.
• Need ignored or hidden files: add --include-hidden and/or --no-respect-gitignore.
• Scriptable output: use --format porcelain (TSV) or --format porcelain-z (NUL-delimited).
• Get detailed help: vexor search --help.
• Config issues: vexor doctor or vexor config --show reports effective values and their origins.

Examples

# Find CLI entrypoints / commands
vexor search "typer app commands" --top 5

# Search docs by headings/sections
vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain

# Locate config loading/validation logic
vexor search "config loader" --path . --mode code --ext .py

# Exclude tests and JavaScript files
vexor search "config loader" --path . --exclude-pattern tests/** --exclude-pattern .js

Tips

• First time search will index files (may take a minute). Subsequent searches are fast. Use longer timeouts if needed.
• Results return similarity ranking, exact file location, line numbers, and matching snippet preview.
• Combine --ext with --exclude-pattern to focus on a subset (exclude rules apply on top).