SemTools

// Overview

SemTools is a command-line tool from LlamaIndex, written in Rust, that brings semantic search and document parsing to the shell. It is one binary with four subcommands: `parse` turns PDF, DOCX, PPTX and other documents into Markdown, `search` finds the lines that match a query by meaning rather than exact text, `ask` runs an AI agent with search and read tools over a set of files, and `workspace` caches embeddings so repeat searches over large collections are faster.

Search runs locally. It embeds text with model2vec using the multilingual potion-multilingual-128M static embedding model, scores matches by cosine similarity and returns each hit with a configurable number of surrounding lines. Results can be capped by a distance threshold or a top-k count, and printed as JSON. Parsing is different: by default `parse` sends files to the LlamaParse API, so it needs a LlamaIndex Cloud API key, and `ask` needs an OpenAI key or any OpenAI-compatible endpoint set through `--base-url` or the config file.

The design is Unix-first: every subcommand reads stdin and writes to stdout, so SemTools chains with `grep`, `find`, `xargs` and `cat` in ordinary pipelines. The project also documents using it as a tool for coding agents such as Claude Code, Cursor or Gemini CLI. You describe SemTools in the agent's `CLAUDE.md` or `AGENTS.md`, and the agent can then parse and search files it could not read on its own. The repository's walkthrough uses a folder of more than 900 conference papers as its example.

// What it does

• `parse` converts PDF, DOCX, PPTX and other formats to Markdown through LlamaParse, with caching, retries and concurrent requests
• Local semantic keyword search with model2vec multilingual embeddings, cosine similarity and per-line context windows
• `ask` agent that answers questions over a document collection using search and read tools, against OpenAI or any OpenAI-compatible API
• Workspaces under `~/.semtools/workspaces/` that cache embeddings, re-embed changed files automatically and prune removed ones
• Unix-friendly stdin/stdout handling, JSON output and tunable `--max-distance`, `--top-k` and `--n-lines`
• One config file (`~/.semtools_config.json`), with CLI flags taking priority over the file and the file over environment variables

// Getting started

Install the binary, set the API keys for the subcommands that need them, then parse and search. Only `search` and `workspace` run fully locally: `parse` calls LlamaParse by default and `ask` calls an OpenAI-compatible model.

npm i -g @llamaindex/semtools

# or with cargo
cargo install semtools

# only the parse feature
cargo install semtools --no-default-features --features=parse

export LLAMA_CLOUD_API_KEY="your_llama_cloud_api_key_here"
export OPENAI_API_KEY="your_openai_api_key_here"

semtools parse my_dir/*.pdf
semtools search "some keywords" *.txt --max-distance 0.3 --n-lines 5
find . -name "*.md" | xargs semtools parse | xargs semtools search "installation"
semtools ask "What are the main findings?" papers/*.txt

semtools workspace use my-workspace
export SEMTOOLS_WORKSPACE=my-workspace
semtools search "some keywords" ./some_large_dir/*.txt --n-lines 5 --top-k 10
semtools workspace status
semtools workspace prune

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Search a folder of PDFs or Word documents by meaning from the terminal, without standing up a vector database
• Give a coding agent like Claude Code the ability to parse and semantically search files it cannot read natively
• Build shell pipelines that mix exact-match `grep` filtering with semantic search and save the results
• Ask questions across a document collection with an agent pointed at OpenAI or a self-chosen OpenAI-compatible endpoint

// How SemTools compares

SemTools alongside other open-source rerank, search & hybrid tools AI/TLDR tracks, ranked by GitHub stars.