RAG-CLI

Local CLI for taxonomy-based document classification, indexing, and semantic search using embeddings.

Setup

Install dependencies:

pnpm install

Configure .env:

RAG_CLI_DB=./rag.sqlite
RAG_CLI_CATEGORIES_DB=./rag-categories.sqlite
RAG_CLI_EMBEDDING_PROVIDER=llama.cpp
RAG_CLI_EMBEDDING_URL=http://localhost:8080/embedding
RAG_CLI_EMBEDDING_MODEL=granite-embedding-107m-multilingual
RAG_CLI_EMBEDDING_DIMENSIONS=384

The embedding endpoint must accept POST /embedding.

Basic usage

1. Sync categories

categories.yml is the source of truth for categories.

pnpm run start categories sync assets/taxonomy/categories.yml

This embeds every category and stores it in the categories database.

2. Classify a text or file

pnpm run start classify assets/docs/doc.txt

This compares the input with the already-synced categories database.

3. Index a text, file, or URL

pnpm run start index assets/docs/doc.txt --metadata '{"fileName":"assets/docs/doc.txt"}'
pnpm run start index https://example.com/article --metadata '{"url":"https://example.com/article"}'

This splits the document into chunks and stores each chunk in the documents database with:

• chunk embedding
• best matching category
• user metadata
• chunk metadata such as chunkIndex, chunkCount, chunkStart, and chunkEnd

Example output:

{
  "chunks": 3,
  "ids": [1, 2, 3]
}

4. Search indexed documents

pnpm run start search "Microsoft BASIC" --limit 5

Search returns the best scoring indexed texts with category and metadata (KNN via sqlite-vec).

5. Inspect database stats

pnpm run start stats

Or:

pnpm run start inspect

This prints a JSON summary of the documents and categories databases.

6. Find indexed chunks by filter

pnpm run start find --file machinelearning
pnpm run start find --text pipeline
pnpm run start find --category llms

You can combine filters and control pagination with --limit and --offset.

Taxonomy format

Example:

version: 1

categories:
  - id: software-architecture
    path: "Tecnologia / Desenvolupament / Arquitectura"
    description: "Notes sobre disseny de software."
    examples:
      - "Clean Architecture"
      - "DDD"

Build

pnpm run build