@tryformation/querylight-cli 0.2.2 → 0.2.4

package/README.md

@@ -16,6 +16,7 @@ It is designed for local, inspectable workflows:
 - chunk documents for retrieval
 - build a portable local Querylight index
 - search and generate retrieval context for external agents and tools
+- serve an OpenSearch-like `_search` API over one or more local knowledge bases
 - inspect workspace state, diffs, and change reports
 
 ## Install
@@ -23,7 +24,7 @@ It is designed for local, inspectable workflows:
 Run without installing globally:
 
 ```bash
-bunx @tryformation/querylight-cli init
+bunx --bun @tryformation/querylight-cli init
 ```
 
 For agent and Python automation examples that use `bunx` and `uv`, see [`examples/skills/qli-bunx-uv/SKILL.md`](https://github.com/formation-res/querylight-cli/blob/main/examples/skills/qli-bunx-uv/SKILL.md).
@@ -43,9 +44,11 @@ npx qli --help
 If you prefer to avoid a local install, use:
 
 ```bash
-bunx @tryformation/querylight-cli --help
+bunx --bun @tryformation/querylight-cli --help
 ```
 
+Use `bunx --bun` for repeated or concurrent `bunx` calls. `bunx` respects the CLI shebang by default and otherwise starts `qli` through `node`.
+
 ## Release
 
 Publish releases from semantic version tags such as `0.1.1`.
@@ -105,6 +108,10 @@ Search it:
 ```bash
 qli search "API authentication"
 qli search --source-type rss --since 2026-05-01 --has-publication-date
+qli search-json '{"query":{"match":{"text":"API authentication"}},"size":5}'
+curl -X POST http://127.0.0.1:3000/_search \
+  -H 'content-type: application/json' \
+  -d '{"query":{"match":{"text":"API authentication"}},"size":5}'
 ```
 
 Find related documents for an existing one:
@@ -119,6 +126,16 @@ Generate retrieval context:
 qli context "How do I authenticate API requests?" --top-k 8
 ```
 
+Serve the lexical index over HTTP:
+
+```bash
+qli serve
+```
+
+`qli serve` loads the current workspace index once at startup and reuses it for each request.
+Use `POST /_search` or `POST /<configured-index-name>/_search` for a single workspace.
+Use `POST /<directory-name>/_search` when `--workspace` points to a directory whose children each contain their own `.kb` workspace.
+
 ## 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`:
@@ -127,7 +144,7 @@ The repository includes an example skill for running `qli` without a global inst
 
 It covers:
 
-- running `qli` with `bunx @tryformation/querylight-cli`
+- running `qli` with `bunx --bun @tryformation/querylight-cli`
 - using `--json` for automation and agents
 - calling `qli search` and `qli context` from Python with `subprocess`
 
@@ -361,6 +378,7 @@ qli search --source-type rss,page --since 2026-05-01 --has-publication-date --to
 qli search --source-name "Release Feed,Company Blog" --uri-prefix https://example.com/news,https://example.com/blog
 qli search --source-type rss,page --top-k 25 --json
 qli search "authentication" --json
+qli search-json '{"query":{"bool":{"filter":[{"term":{"sourceType":"rss"}}]}},"size":10}' --json
 ```
 
 Build retrieval context:
@@ -370,6 +388,18 @@ qli context "How do I configure the API?"
 qli context "What changed in pricing?" --top-k 12 --max-chars 12000
 ```
 
+Serve the lexical index over HTTP:
+
+```bash
+qli serve
+qli serve --workspace ./docs/.kb --port 4000
+qli serve --workspace ./kbs --host 0.0.0.0 --port 4000
+```
+
+For a single workspace, use `POST /_search` or `POST /<configured-index-name>/_search`.
+For a directory of knowledge bases, use `POST /<directory-name>/_search`.
+The request body must be a Querylight JSON DSL object.
+
 ### Change Inspection
 
 ```bash

package/dist/cli/format.d.ts

@@ -1,4 +1,4 @@
-import type { RelatedDocumentResult, SearchResult, Source } from "../types/models.js";
+import type { RelatedDocumentResult, SearchResponseData, Source } from "../types/models.js";
 export declare function formatSourcesTable(sources: Source[]): string;
-export declare function formatSearchResults(results: SearchResult[]): string;
+export declare function formatSearchResults(response: SearchResponseData): string;
 export declare function formatRelatedDocuments(results: RelatedDocumentResult[]): string;