Querion / Reference
CLI and web API
The querion commands, flags and exit codes, the web UI, the JSON API endpoints, and how to expose the server safely.
On this page
Querion has two front ends over the same run loop: a command-line interface (CLI) for one question at a time, and a web server with a JavaScript Object Notation (JSON) application programming interface (API).
Commands
querion check validate config, test the database and the claude CLI
querion introspect [-o FILE] write a schema Markdown file from the live database
querion ask "question" answer one question in the terminal
querion serve [--host --port] run the web app and JSON API
Global flags:
-c,--config PATH: the config file. Place it before the subcommand:querion -c path/to/querion.yaml check.--version: print the version.
ask joins all its arguments into one question, so quotes are optional. Quoting is still safer, because the shell would otherwise read characters such as ? and *.
serve defaults to --host 127.0.0.1 and --port 8000, and runs a single uvicorn worker. Run state is held in memory, so do not raise the worker count.
introspect prints to standard output, or to the file given with -o.
Exit codes
0: the command ran. This includescheckwhen a line reportsERRORorNOT FOUND, andaskwhen the question was refused or ended with statuserror. Read the output, not only the exit code.1: the command could not run, for example because the config file is missing or invalid. The message prints aserror: ...on standard error.introspectwith nodatabase.dsnalso exits with 1, after printingno database.dsn configured.2: invalid arguments, reported by the argument parser.
Web UI
querion serve serves a single-page Alpine.js user interface (UI) at /. It has an ask box, three example questions, step-by-step progress, charts drawn by Chart.js, and a “Show SQL” list of every Structured Query Language (SQL) statement that ran without error. The page loads Chart.js and Alpine.js from cdn.jsdelivr.net, and a font from Google Fonts, so the browser needs access to those hosts.
JSON API
Why the API is asynchronous: one question can take several model calls, and each call may take up to 200 seconds. Holding one Hypertext Transfer Protocol (HTTP) request open for all of that is fragile, so POST /api/ask starts the run in a background thread and returns an id at once. The client then polls.
GET /api/config:company,model,sources(names),has_database,troveanddaily_limit.GET /api/health:ok,claude_cli(whether the binary was found),database(ok,errorornot-configured) andsources.okis alwaystruewhen the server answers, and the database check runsSELECT 1on every call.POST /api/ask: body{"question": "..."}. Returns{"id": ..., "remaining": ...}, whereremainingis the caller’s questions left today, or-1with no cap. An empty question returns 400. A question the firewall refuses returns 200 with{"refused": "..."}and does not count against the cap. Hitting the daily cap returns 429 with{"refused": "Daily limit reached. Resets ..."}.GET /api/ask/{id}: poll a run. Unknown ids return 404 with{"error": "unknown run"}.
While a run is in progress, the poll returns status: "running" with question, steps, answer, charts, sqls, created and remaining. steps grows as each step finishes. When the run ends, status becomes done, refused or error, and the record also has refused. For a refused run, answer holds the refusal text.
Runs older than one hour are removed when the server accepts the next question.
Example with curl
curl -s -X POST http://127.0.0.1:8000/api/ask \
-H 'Content-Type: application/json' \
-H 'X-Querion-User: alice' \
-d '{"question": "top 10 products by revenue this quarter"}'
# {"id":"<12 hex characters>","remaining":49}
curl -s http://127.0.0.1:8000/api/ask/<id>
Poll until status is no longer running. The web UI polls every 1.4 seconds. charts holds the chart specs; the format is in Architecture.
Caller identity and the daily cap
The cap key is the X-Querion-User header if present, otherwise the client’s Internet Protocol (IP) address. A client can send any header value, so the cap is a cost control, not an access control. Behind a reverse proxy, Querion may see every request as coming from the proxy’s address, so have the proxy set X-Querion-User.
Exposure
The server has no login. Run ids are random, but the poll endpoint does not check who is asking, so anyone who can reach the server can read a run whose id they have. Put querion serve behind your own authentication, such as single sign-on (SSO), a reverse proxy or an IP allowlist, before exposing it beyond localhost.
Run it as one process. Runs in progress and the daily counter live in that process, so several instances behind a load balancer would lose runs between polls, and each would keep its own counter. Each accepted question starts its own thread and its own claude processes, with no queue, so size the host for the number of questions you expect at once.