RAGed

CLI (raged)

Command-line tool for indexing Git repositories, ingesting arbitrary files, and querying the RAG API.

Build

cd cli
npm install
npm run build

Commands

index

Clone a Git repository, scan for text files, and ingest them into the RAG API.

node dist/index.js index --repo <git-url> [options]
Flag Default Description
--repo (required) Git URL to clone
--api http://localhost:8080 RAG API URL
--collection docs Collection name
--branch (default branch) Git branch to clone
--repoId (repo URL) Stable identifier for this repo
--token (env RAGED_API_TOKEN) Bearer token for auth
--include (all) Only index files matching this path prefix
--exclude (none) Skip files matching this path prefix
--maxFiles 4000 Maximum files to process
--maxBytes 500000 Maximum file size in bytes
--keep false Keep the cloned temp directory
--enrich true Enable async enrichment
--no-enrich - Disable async enrichment
--doc-type (auto-detect) Override document type detection

query

Search the RAG API for relevant chunks.

node dist/index.js query --q "<search text>" [options]
Flag Default Description
--q / --query (required) Search query text
--api http://localhost:8080 RAG API URL
--collection docs Collection name
--topK 8 Number of results to return
--repoId (none) Filter by repository ID
--pathPrefix (none) Filter by file path prefix
--lang (none) Filter by language
--since (none) Temporal lower bound for ingestedAt (today, yesterday, <N>d, <N>y, or ISO 8601)
--until (none) Temporal upper bound for ingestedAt (today, yesterday, <N>d, <N>y, or ISO 8601)
--filterField (none) Structured filter condition (repeatable). Format: field:op:value or field:op
--filterCombine and How to join --filterField conditions (and or or)
--strategy (auto) Force query strategy: semantic, metadata, graph, hybrid
--verbose false Always print routing decision and timing for all results
--token (env RAGED_API_TOKEN) Bearer token for auth

Strategy-aware output

By default, raged routes each query automatically. You can force a specific strategy with --strategy or inspect routing with --verbose.

Routing line (shown when strategy ≠ semantic, or always with --verbose):

routing: <strategy>  (<method>, <durationMs>ms)

Output per strategy:

Strategy Score Text shown Extras
semantic cosine similarity snippet (280 chars) routing line only with --verbose
metadata 1.00 filter match: field=val … routing line always shown
graph cosine similarity snippet routing line + graph documents section
hybrid blended score snippet routing line + graph documents section

Semantic result (default):

#1  score=0.82
collection: docs
source: src/auth.ts
Handles authentication via JWT tokens...

Semantic result with --verbose:

#1  score=0.82
collection: docs
source: src/auth.ts
routing: semantic  (rule, 8ms)
Handles authentication via JWT tokens...

Metadata result:

#1  score=1.00
collection: docs
source: src/auth.ts
routing: metadata  (rule, 3ms)
filter match: lang=ts, docType=code

Graph result:

#1  score=0.78
collection: docs
source: src/auth.ts
routing: graph  (rule, 11ms)
Handles authentication via JWT tokens...

--- graph documents (2) ---
[G1]  src/auth.ts
[G2]  src/auth.test.ts

ingest

Ingest arbitrary files (PDFs, images, text, Slack exports) into the RAG API.

node dist/index.js ingest --file <path> [options]
node dist/index.js ingest --dir <path> [options]
Flag Default Description
--file - Single file to ingest (mutually exclusive with –dir)
--dir - Directory to ingest (mutually exclusive with –file)
--api http://localhost:8080 RAG API URL
--collection docs Collection name
--token (env RAGED_API_TOKEN) Bearer token for auth
--maxFiles 4000 Maximum files to process from directory
--enrich true Enable async enrichment
--no-enrich - Disable async enrichment
--doc-type (auto-detect) Override document type (code, text, pdf, image, slack)

Supported file types:

enrich

Trigger and monitor async enrichment tasks.

node dist/index.js enrich [options]
Flag Default Description
--api http://localhost:8080 RAG API URL
--collection docs Collection name
--token (env RAGED_API_TOKEN) Bearer token for auth
--force false Re-enqueue all items (including already-enriched)
--stats-only false Show enrichment stats without enqueueing

Behavior:

Examples:

# Show enrichment stats only (no enqueueing)
node dist/index.js enrich --stats-only

# Show stats and enqueue pending items (default)
node dist/index.js enrich

# Show stats and force re-enrichment of all items
node dist/index.js enrich --force

graph

Query the knowledge graph for entity information.

node dist/index.js graph --entity <name> [options]
Flag Default Description
--entity (required) Entity name to look up
--api http://localhost:8080 RAG API URL
--token (env RAGED_API_TOKEN) Bearer token for auth

Example:

node dist/index.js graph --entity "AuthService"

Output:

=== Entity: AuthService ===
Type: class
Description: Handles user authentication

=== Connections (2) ===
  → JWT (uses)
  ← UserService (relates_to)

=== Related Documents (3) ===
  - my-repo:src/auth.ts:0
  - my-repo:src/auth.ts:1
  - my-repo:docs/auth.md:0

Index Lifecycle

flowchart LR
    A[git clone<br/>--depth 1] --> B[Scan files]
    B --> C{Text file?}
    C -->|No| D[Skip]
    C -->|Yes| E{Size OK?}
    E -->|No| D
    E -->|Yes| F{Prefix filter?}
    F -->|Excluded| D
    F -->|Included| G[Read file]
    G --> H[Add to batch]
    H --> I{Batch full?}
    I -->|Yes| J[POST /ingest]
    I -->|No| B
    J --> B

    style D fill:#ffcdd2
    style J fill:#c8e6c9

Authentication

Two ways to provide the auth token:

  1. Flag: --token my-token
  2. Environment variable: export RAGED_API_TOKEN=my-token

The flag takes precedence over the environment variable.

Examples

Index a public repo:

node dist/index.js index \
  --repo https://github.com/fastify/fastify.git \
  --api http://localhost:8080 \
  --collection fastify-docs \
  --include docs/

Query with filters:

node dist/index.js query \
  --api http://localhost:8080 \
  --q "request validation" \
  --topK 5 \
  --collection fastify-docs \
  --lang md
This site is open source. Improve this page.