Querylight CLI

Querylight CLI is a TypeScript command line application for building and querying local knowledge bases with Querylight TS.

• Package: @tryformation/querylight-cli
• Binary: qli
• Runtime: Node.js 22+

It is designed for local, inspectable workflows:

• ingest files, directories, URLs, and websites
• normalize content into Markdown-like text
• chunk documents for retrieval
• build a portable local Querylight index
• search and generate retrieval context for external agents and tools
• inspect workspace state, diffs, and change reports

Install

Run without installing globally:

bunx @tryformation/querylight-cli init

For agent and Python automation examples that use bunx and uv, see examples/skills/qli-bunx-uv/SKILL.md.

Install as a dependency:

npm install @tryformation/querylight-cli

Then run:

npx qli --help

If you prefer to avoid a local install, use:

bunx @tryformation/querylight-cli --help

Release

Publish releases from semantic version tags such as 0.1.1.

The GitHub Actions publish workflow publishes @tryformation/querylight-cli to the public npm registry.

Configure npm trusted publishing for this repository before the first release. The publish workflow uses GitHub OIDC and does not use an NPM_TOKEN secret.

Local Development with npm link

If you are working from a local checkout of this repository and want a real qli command available in any directory:

cd /path/to/querylight-cli
npm install
npm run build
npm link

After that, you can use qli anywhere on your machine:

cd /some/project
qli --help

To remove the linked command later:

npm unlink -g @tryformation/querylight-cli

Quick Start

Initialize a workspace:

qli init

Add a local docs directory:

qli source add directory ./docs --name "Local Docs" --tag docs

Build the knowledge base:

qli rebuild

Search it:

qli search "API authentication"
qli search --source-type rss --since 2026-05-01 --has-publication-date

Find related documents for an existing one:

qli related <document-id-or-uri>

Generate retrieval context:

qli context "How do I authenticate API requests?" --top-k 8

Example Skill: qli with bunx and uv

The repository includes an example skill for running qli without a global install and calling it from Python with uv:

• examples/skills/qli-bunx-uv/SKILL.md

It covers:

• running qli with bunx @tryformation/querylight-cli
• using --json for automation and agents
• calling qli search and qli context from Python with subprocess

Example: Index querylight.tryformation.com

This example uses a local linked build of qli to create a test knowledge base for the Querylight documentation website.

1. Link the local CLI:

cd /path/to/querylight-cli
npm install
npm run build
npm link

2. Create a fresh test workspace:

mkdir -p ~/querylight-ts-search
cd ~/querylight-ts-search

3. Initialize the knowledge base:

qli init

4. Add the Querylight website as a source:

qli source add website https://querylight.tryformation.com \
  --name "Querylight TS Docs" \
  --max-depth 2 \
  --max-pages 50 \
  --include /docs/ \
  --tag docs

5. Build the local index:

qli rebuild

6. Inspect and query the result:

qli status
qli source list
qli search "BM25 ranking"
qli context "How does Querylight TS handle BM25 ranking?" --top-k 8

If you want the workspace somewhere else, use:

qli --workspace /custom/path/.kb <command>

Workspace

The default workspace is .kb/.

.kb/
  config.yaml
  sources/
    sources.jsonl
  documents/
    documents.jsonl
  chunks/
    chunks.jsonl
  raw/
  normalized/
  indexes/
    latest.json
    latest.meta.json
  runs/
  logs/

Use a custom workspace with:

qli --workspace ./my-kb <command>

Supported Sources

Current source types:

• file
• directory
• url
• website
• rss
• markdown
• text

Current local file ingestion support:

• .md
• .txt
• .html
• .htm
• .pdf
• .docx

Commands

All commands support:

--workspace <path>
--config <path>
--json
--verbose
--quiet

Initialize

qli init
qli init --workspace ./kb
qli init --force

Manage Sources

Add sources:

qli source add file ./docs/guide.md --name "Guide"
qli source add directory ./docs --name "Docs" --tag docs
qli source add url https://example.com/docs/auth --name "Auth Page"
qli source add website https://example.com --name "Example Site" --max-depth 2 --max-pages 50
qli source add rss https://example.com/feed.xml --name "Release Feed"

List and manage them:

qli source list
qli source config <source-id> --retention-days 30
qli source config <source-id> --name "Docs Feed" --tag rss docs
qli source disable <source-id>
qli source enable <source-id>
qli source remove <source-id>

Find Related Documents

Build dense vectors first:

qli models pull --dense
qli rebuild

Or pull every model that is available on the current machine:

qli models pull

Then ask for documents related to an existing document id or URI:

qli related <document-id>
qli related https://example.com/docs/auth

Ingest, Chunk, Index

qli ingest
qli chunk
qli index build

Run the full pipeline:

qli rebuild
qli rebuild --source <source-id>
qli rebuild --changed-only

Search and Retrieval

Search:

qli search "pricing API limits"
qli search "refund policy" --tag support --top-k 20
qli search --source-type rss,url --since 2026-05-01 --has-publication-date --top-k 25
qli search --source-name "Release Feed,Company Blog" --uri-prefix https://example.com/news,https://example.com/blog
qli search --source-type rss,url --top-k 25 --json
qli search "authentication" --json

Build retrieval context:

qli context "How do I configure the API?"
qli context "What changed in pricing?" --top-k 12 --max-chars 12000

Change Inspection

qli diff
qli diff --source <source-id>
qli diff --document <document-id>
qli diff --since 2026-05-01

qli report changes --since 2026-05-01
qli report changes --source <source-id>

Workspace Inspection

qli status
qli doctor

JSON Output

Agent-facing and automation-friendly commands support --json.

The output envelope is:

{
  "ok": true,
  "command": "search",
  "workspace": "/absolute/path/.kb",
  "version": "0.1.0",
  "data": {}
}

Docker

Build the image:

docker build -t querylight-cli .

Run commands against a mounted workspace:

docker run --rm -v "$PWD:/data" querylight-cli init --workspace /data/.kb
docker run --rm -v "$PWD:/data" querylight-cli rebuild --workspace /data/.kb
docker run --rm -v "$PWD:/data" querylight-cli search --workspace /data/.kb "authentication"

Development

Install dependencies:

npm install

Run checks:

npm run check

Build:

npm run build