querius

querius is a Node.js CLI + library that:

• searches DuckDuckGo (HTML endpoint)
• extracts readable text from top results (Readability + JSDOM)
• optionally calls an OpenAI-compatible chat model (OpenAI or OpenRouter)

Install

npm i querius

Or run without installing:

npx querius "your question"

Quickstart (CLI)

1) No LLM (just search + extract)

Useful for debugging sources/context.

npx querius "what is the capital of france?" --no-llm

2) With OpenAI

export OPENAI_API_KEY="YOUR_OPENAI_KEY"
npx querius "what is the capital of france?" --provider openai --model gpt-4o-mini

3) With OpenRouter

You must use a real OpenRouter key (often looks like sk-or-v1-...).

export OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY"
npx querius "what is the capital of france?" --provider openrouter --model openai/gpt-4o-mini

CLI options

querius "your question" [options]

• --provider <openrouter|openai>: which API to use
• --model <name>: model name (provider-specific)
• --api-key <key>: API key override (recommended: use env vars instead)
• --max-results <n>: how many search results to use (default 3)
• --concurrency <n>: parallel fetch/extraction (default 3)
• --use-playwright: enable JS-render fallback (slower; helps for JS-heavy sites)
• --no-llm: skip model call; print context preview only
• --json: print JSON output (answer + sources + extracted context)
• -h, --help: help

Example: JSON output

OPENAI_API_KEY="..." npx querius "capital of france" --provider openai --json

Environment variables

OpenRouter

• OPENROUTER_API_KEY (required for OpenRouter)
• OPENROUTER_MODEL (optional default model)
• OPENROUTER_BASE_URL (optional; default https://openrouter.ai/api/v1)
• OPENROUTER_HTTP_REFERER (optional)
• OPENROUTER_X_TITLE (optional; default querius)

OpenAI

• OPENAI_API_KEY (required for OpenAI)
• OPENAI_MODEL (optional default model)
• OPENAI_BASE_URL (optional; default https://api.openai.com/v1)

Generic (optional)

• MODEL (fallback model name)
• PROVIDER / QUERIUS_PROVIDER (fallback provider)

Notes

• The CLI loads .env automatically (uses dotenv).
• The library does not load .env (pass keys via process.env or parameters).

Library usage (in your code)

ESM (recommended) — .mjs or "type": "module"

import { runQuerIus } from "querius";

const out = await runQuerIus({
  query: "What is the capital of France?",
  provider: "openai", // or "openrouter"
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

console.log(out.error || out.answer);

CommonJS project (require) — use dynamic import

If your project is CommonJS, don’t use top-level await + require() together.

(async () => {
  const { runQuerIus } = await import("querius");
  const out = await runQuerIus({
    query: "What is the capital of France?",
    provider: "openai",
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
  });
  console.log(out.error || out.answer);
})();

What runQuerIus() returns

{
  query: string,
  results: Array<{ title: string, url: string, content: string }>,
  context: string,
  answer: string | null,
  error: string | null
}

Tips / troubleshooting

“Missing Authentication header”

This almost always means:

• you chose provider: "openrouter" but did not provide a real OPENROUTER_API_KEY, or
• you used an OpenAI key in OPENROUTER_API_KEY (OpenRouter requires its own key)

Fix: set the correct key for the provider you’re using.

Node warning: MODULE_TYPELESS_PACKAGE_JSON

Your file uses ESM syntax (import, top-level await) but your project doesn’t specify module type. Fix:

• add "type": "module" in your project’s package.json, or
• rename your script to .mjs

Could not parse CSS stylesheet

This is noisy output from jsdom on some pages. It usually doesn’t break extraction; safe to ignore.

Security best practices

• Never hardcode API keys in code.
• Use environment variables (OPENAI_API_KEY, OPENROUTER_API_KEY) or .env locally.
• If you ever pasted a key into logs/chat, rotate/revoke it.