CLI Reference

Three command-line programs ship under examples/ and build to the project's build/ directory. They share the argument-parsing harness in mormot.ai.cli.pas and follow consistent conventions:

  • Every program accepts --help and prints a stable usage block to stdout, then exits with code 0.
  • Argument errors (unknown flag, missing required flag, missing value for a flag) print to stderr and exit with code 1.
  • Runtime errors after argument parsing succeeded (database unreachable, Ollama down, schema mismatch) print the exception class + message to stderr and exit with code 2.
  • Successful runs exit with code 0.

The connection-string format for --pg is the libpq-style key=value list separated by ;:

host=localhost;port=5432;dbname=mormot2_pgvector_test;user=postgres;password=...

01_ingest_mormot2

Walks a Pascal source path, chunks every unit, embeds each chunk, and inserts one row per chunk into the canonical mormot_chunks table.

01_ingest_mormot2 --src DIR --pg CONNSTR
                  [--ollama URL] [--model NAME] [--threads N]
                  [--reset] [--libpq PATH]
Flag Required Default Purpose
--src DIR yes — Source root: a single file or a directory.
--pg CONNSTR yes — PostgreSQL connection string.
--ollama URL no http://localhost:11434 Ollama base URL.
--model NAME no embeddinggemma Embedding model name.
--threads N no 4 Parallel embed worker count (forwarded to IngestParallel).
--reset no off Drop the target table before ingest.
--libpq PATH no resolved from PATH Override the libpq library path.

Output (success):

files=1  chunks=73  rows=73  elapsed=10125ms

Status messages like Connected, Setting up schema..., Ingesting... go to stderr; the stats line above is the only thing printed to stdout.

02_query_cli

Embeds a single query and runs the hybrid retrieval against mormot_chunks.

02_query_cli --pg CONNSTR --query "..."
             [--top-k N] [--family NAME] [--alpha F]
             [--ollama URL] [--model NAME]
             [--table NAME] [--dim N] [--libpq PATH]
Flag Required Default Purpose
--pg CONNSTR yes — PostgreSQL connection string.
--query TEXT yes — Natural-language question.
--top-k N no 5 Number of results to return.
--family NAME no empty Restrict to one family (core, orm, db, rest, net, crypt, …). Empty = all.
--alpha F no 0.7 Hybrid weight: 1.0 = vector pure, 0.0 = text pure.
--ollama URL no http://localhost:11434 Ollama base URL.
--model NAME no embeddinggemma Embedding model name.
--table NAME no mormot_chunks Target table name.
--dim N no 0 (probe) Embedding dimension. 0 means “probe at startup”.
--libpq PATH no — Override libpq path.

Output: one line per result, with rank, family tag, symbol, unit:line range, three score components, and an indented 200-character excerpt.

03_chat_cli

Retrieves top-k chunks, builds a RAG prompt, sends it to a configurable LLM, prints the model's answer.

03_chat_cli --pg CONNSTR --query "..."
            --llm-url URL --llm-model NAME
            [--top-k N] [--family NAME] [--alpha F]
            [--ollama URL] [--model NAME]
            [--table NAME] [--dim N] [--libpq PATH]
Flag Required Default Purpose
--pg CONNSTR yes — PostgreSQL connection string.
--query TEXT yes — Natural-language question.
--llm-url URL yes — LLM endpoint. Special sentinel stub selects the no-network TStubLlmClient.
--llm-model NAME yes — LLM model name (any Ollama generative model).
--top-k N no 5 Chunks to retrieve.
--family NAME no empty Restrict retrieval to one family.
--alpha F no 0.7 Hybrid weight.
--ollama URL no http://localhost:11434 Embedder Ollama base URL.
--model NAME no embeddinggemma Embedder model.
--table NAME no mormot_chunks Target table.
--dim N no 0 (probe) Embedder dimension.
--libpq PATH no — Override libpq path.

The chat program prints provenance (one line per retrieved chunk with its unit:line_start-line_end and the three score components) to stderr, and the final LLM answer to stdout. This separation lets you pipe the answer into another tool while keeping a paper-trail of where each fact came from.

Pass --llm-url stub when you want to verify wiring without an LLM running locally; the stub returns a documented placeholder string.

Exit codes

Code Constant Meaning
0 CLI_EXIT_SUCCESS Normal success; usage block printed when invoked with --help.
1 CLI_EXIT_ARG_ERROR Unknown flag, missing required flag, or missing value.
2 CLI_EXIT_RUNTIME_ERROR Argument parsing succeeded but a runtime exception escaped (database unreachable, Ollama down, server-side error, …).

The mormot.ai.cli.pas unit re-exports these constants so library callers stay in sync with the CLI conventions.

demo_real

A diagnostic helper, not a production CLI. Hard-coded to point at one Pascal source file (default <MORMOT2>/src/orm/mormot.orm.client.pas), runs the three canonical queries from the design brief, and prints the provenance + excerpts. Useful as a sanity check after a fresh build.

build\demo_real.exe                        # default file
build\demo_real.exe path\to\unit.pas       # explicit path