npm i -g @llamaindex/semtools

# install entire crate
cargo install semtools
# install only select features
cargo install semtools --no-default-features --features=parse

# Parse some files
semtools parse my_dir/*.pdf
# Search some (text-based) files
semtools search "some keywords" *.txt --max-distance 0.3 --n-lines 5
# Ask questions about your documents using an AI agent
semtools ask "What are the main findings?" papers/*.txt
# Combine parsing and search
semtools parse my_docs/*.pdf | xargs search "API endpoints"
# Ask a question to a set of files
semtools ask "Some question?" *.txt
# Combine parsing with the ask agent
semtools parse research_papers/*.pdf | xargs ask "Summarize the key methodologies"
# Ask based on stdin content
cat README.md | semtools ask "How do I install SemTools?"

# Combine with grep for exact-match pre-filtering and distance thresholding
semtools parse *.pdf | xargs cat | grep -i "error" | semtools search "network error" --max-distance 0.3
# Pipeline with content search (note the 'xargs' on search to search files instead of stdin)
find . -name "*.md" | xargs semtools parse | xargs semtools search "installation"
# Combine with grep for filtering (grep could be before or after parse/search!)
semtools parse docs/*.pdf | xargs semtools search "API" | grep -A5 "authentication"
# Save search results from stdin search
semtools parse report.pdf | xargs cat | semtools search "summary" > results.txt

# Create or select a workspace
# Workspaces are stored in ~/.semtools/workspaces/
semtools workspace use my-workspace
> Workspace 'my-workspace' configured.
> To activate it, run:
>   export SEMTOOLS_WORKSPACE=my-workspace
>
> Or add this to your shell profile (.bashrc, .zshrc, etc.)
# Activate the workspace
export SEMTOOLS_WORKSPACE=my-workspace
# All search commands will now use the workspace for caching embeddings
# The initial command is used to initialize the workspace
semtools search "some keywords" ./some_large_dir/*.txt --n-lines 5 --top-k 10
# If documents change, they are automatically re-embedded and cached
echo "some new content" > ./some_large_dir/some_file.txt
semtools search "some keywords" ./some_large_dir/*.txt --n-lines 5 --top-k 10
# If documents are removed, you can run prune to clean up stale files
semtools workspace prune
# You can see the stats of a workspace at any time
semtools workspace status
> Active workspace: arxiv
> Root: /Users/loganmarkewich/.semtools/workspaces/arxiv
> Documents: 3000
> Index: Yes (IVF_PQ)

$ semtools parse --help
A CLI tool for parsing documents using various backends
Usage: semtools parse [OPTIONS] <FILES>...
Arguments:
  <FILES>...  Files to parse
Options:
  -c, --config <CONFIG>    Path to the config file. Defaults to ~/.semtools_config.json
  -b, --backend <BACKEND>  The backend type to use for parsing. Defaults to `llama-parse` [default: llama-parse]
  -v, --verbose            Verbose output while parsing
  -h, --help               Print help

$ semtools search --help
A CLI tool for fast semantic keyword search
Usage: semtools search [OPTIONS] <QUERY> [FILES]...
Arguments:
  <QUERY>     Query to search for (positional argument)
  [FILES]...  Files to search, optional if using stdin
Options:
  -n, --n-lines <N_LINES>            How many lines before/after to return as context [default: 3]
      --top-k <TOP_K>                The top-k files or texts to return (ignored if max_distance is set) [default: 3]
  -m, --max-distance <MAX_DISTANCE>  Return all results with distance below this threshold (0.0+)
  -i, --ignore-case                  Perform case-insensitive search (default is false)
  -j, --json                         Output results in JSON format
  -h, --help                         Print help

$ semtools workspace --help
Manage semtools workspaces
Usage: semtools workspace [OPTIONS] <COMMAND>
Commands:
  use     Use or create a workspace (prints export command to run)
  status  Show active workspace and basic stats
  prune   Remove stale or missing files from store
  help    Print this message or the help of the given subcommand(s)
Options:
  -j, --json  Output results in JSON format
  -h, --help  Print help

$ semtools ask --help
A CLI tool for document-based question-answering
Usage: semtools ask [OPTIONS] <QUERY> [FILES]...
Arguments:
  <QUERY>     Query to prompt the agent with
  [FILES]...  Files to search, optional if using stdin
Options:
  -c, --config <CONFIG>      Path to the config file. Defaults to ~/.semtools_config.json
      --api-key <API_KEY>    OpenAI API key (overrides config file and env var)
      --base-url <BASE_URL>  OpenAI base URL (overrides config file)
  -m, --model <MODEL>        Model to use for the agent (overrides config file)
      --api-mode <API_MODE>  API mode to use: 'chat' or 'responses' (overrides config file)
  -j, --json                 Output results in JSON or text format
  -h, --help                 Print help

{
  "parse": {
    "api_key": "your_llama_cloud_api_key_here",
    "num_ongoing_requests": 10,
    "base_url": "https://api.cloud.llamaindex.ai",
    "parse_kwargs": {
      "tier": "agentic",
      "version": "latest",
      "disable_cache": false
    },
    "check_interval": 5,
    "max_timeout": 3600,
    "max_retries": 10,
    "retry_delay_ms": 1000,
    "backoff_multiplier": 2.0
  },
  "ask": {
    "api_key": "your_openai_api_key_here",
    "base_url": null,
    "model": "gpt-4o-mini",
    "max_iterations": 20,
    "api_mode": "responses",  // Can be responses or chat
  }
}

# For parse tool
export LLAMA_CLOUD_API_KEY="your_llama_cloud_api_key_here"
# For ask tool
export OPENAI_API_KEY="your_openai_api_key_here"

semtools ask "What is this about?" docs/*.txt --model gpt-4o --api-key sk-...