Skip to main content

CLI Tutorial

Time to complete: ~10 minutes
Prerequisites: hlquery server running on http://localhost:9200
Goal: Use the current hlquery-cli commands for health checks, collection inspection, search, and maintenance

Overview​

hlquery-cli is the command-line client for a running hlquery server. The current command surface is the one shown by:

./run/hlquery cli help

If you keep the binary on your PATH, you can use hlquery-cli directly. Otherwise run it from the repo with ./run/hlquery cli.

Basic Usage​

hlquery-cli [OPTIONS] <COMMAND> [ARGS...]

Global Options​

OptionDescriptionExample
--url <url>Connect to a specific server URLhlquery-cli --url http://localhost:9201 stats
--host <host>Set server hosthlquery-cli --host 127.0.0.1 --port 9201 stats
--port <port>Set server porthlquery-cli --host localhost --port 9201 stats
--auth <token>Send API tokenhlquery-cli --auth mytoken stats
--ssl-authSend token as both Authorization and X-API-Key over HTTPShlquery-cli --url https://localhost:9200 --auth mytoken --ssl-auth stats
--timeout <seconds>Request timeouthlquery-cli --timeout 10 search products laptop
--rawPrint raw HTTP JSONhlquery-cli --raw stats
-h, --helpShow helphlquery-cli help

Health and Status​

health​

Quick health check against /health and /stats.

hlquery-cli health

stats​

Show server statistics.

hlquery-cli stats
hlquery-cli --raw stats

adv​

Show a more detailed server summary.

hlquery-cli adv

uptime​

Show uptime in human-readable form.

hlquery-cli uptime
hlquery-cli uptime -d

Metrics Note​

There is no hlquery-cli metrics command. Use:

hlquery-cli stats
curl http://localhost:9200/metrics

Use stats for the CLI view, and /metrics for the HTTP metrics endpoint.

Collections​

cols​

List collections.

hlquery-cli cols
hlquery-cli cols --json
hlquery-cli cols --offset 10 --limit 20

info​

Show detailed info for one collection.

hlquery-cli info products

doctotal and coltotal​

Show aggregate collection and document totals.

hlquery-cli doctotal
hlquery-cli doctotal --offset 0 --limit 100
hlquery-cli coltotal

create​

Create a collection.

hlquery-cli create products title content price

delete​

Delete a collection, one document, or a filtered set of documents.

hlquery-cli delete products
hlquery-cli delete products 123
hlquery-cli delete products --filter="category:electronics"

rebuild-counters, repair, verify​

Consistency and repair helpers.

hlquery-cli rebuild-counters
hlquery-cli rebuild-counters products --index
hlquery-cli repair products --index
hlquery-cli verify

Documents​

docs​

List documents from a collection.

hlquery-cli docs products
hlquery-cli docs products 0 50

add​

Add a document.

hlquery-cli add products laptop1 "Gaming Laptop" "High-performance laptop" price=1999.99 category=electronics

open​

Open a single document.

hlquery-cli open products/laptop1
hlquery-cli open products/laptop1 --json
hlquery-cli open products/laptop1 --text

select​

Read one field from one document.

hlquery-cli select title products/laptop1

search​

Search one collection, or use --all before the query for one merged search across collections. The positional values after the query are limit, offset, and sort, in that order.

hlquery-cli search products "laptop"
hlquery-cli search products "laptop" 20 0 "price:desc"
hlquery-cli search products "laptop" 20 0 "price:desc" --exact --highlight
hlquery-cli search --all "research" 20 0
hlquery-cli search --all "research" 20 0 --collections=universities,science --json
hlquery-cli search products "laptop" --fields=title,content
hlquery-cli search products "laptop" --distributed=on
hlquery-cli search products "lapto" --maybe=3,5

In --all mode, limit and offset apply after results from the target collections are merged and sorted. Each JSON hit includes document._collection. --all enables distributed search by default; use --distributed=off when only local collections should be queried. Without --fields, the server uses each collection's searchable fields; --fields=title,content restricts both matching and highlighting to those fields. The maximum global result window is offset + limit = 10000.

sql​

Run a SQL-style query directly through the daemon /sql endpoint.

hlquery-cli sql "SELECT * FROM products LIMIT 5;"
hlquery-cli sql "SELECT COUNT(*) AS total_docs FROM products;"
hlquery-cli sql "SELECT category, AVG(score) AS avg_score FROM products GROUP BY category ORDER BY avg_score DESC;"

colsearch​

Search collection names.

hlquery-cli colsearch prod
hlquery-cli colsearch prd --maybe=2,5

search --all​

Search across every collection through the HTTP /search endpoint and only across non-replica cluster search nodes. Any endpoint configured as a replication slave is excluded from this fanout path, even if that same endpoint is also tagged for distributed search. This prevents master+replica duplicate results during --all searches.

hlquery-cli search --all "laptop"
hlquery-cli search --all "laptop" 20 0 "price:asc" --highlight --collections=products,articles
hlquery-cli search --all "lapto" --maybe=3,5

Talk REPL​

talk is the interactive shell for inspecting collections, running searches, and issuing SQL without rebuilding curl commands by hand.

Start it from the repo:

./run/bin/talk

Or choose a different target server:

./run/bin/talk --host 127.0.0.1 --port 9201

Basic Navigation​

localhost:9200> ls
localhost:9200> use products
localhost:9200|products> ls
localhost:9200|products> open prod_001
localhost:9200|products> search laptop 10 0 price:asc --highlight
localhost:9200|products> cd
localhost:9200> pwd

How src/talk Is Organized​

The talk binary is implemented in src/talk/ and is intentionally split into a small number of files with clear responsibilities:

  • src/talk/entry.cpp

    • Program entrypoint for run/bin/talk.
    • Parses --host, --port, and --command.
    • Builds the target base URL, loads history, installs tab completion, and runs the interactive loop.
    • If -c or --command is used, it executes one command without entering the full REPL loop.

  • src/talk/main.cpp

    • Core implementation of the shell behavior.
    • Contains host and port validation, prompt formatting, endpoint switching, command parsing, and command dispatch.
    • Maps REPL commands such as ls, use, open, search, sql:, exec:, stats, and ping into HLQueryCLI operations.
    • Handles convenience behavior such as endpoint discovery, history file resolution, and user-facing output formatting.

  • src/talk/session.h

    • Shared declarations for talk-specific state and helper functions.
    • Defines TalkState, which tracks the current collection, collection history, and the most recent list results used by commands like open.
    • Declares the helpers used by both the entrypoint and the command implementation, including prompt construction, whitespace trimming, completion, and command execution.

  • src/talk/linenoise.h

    • Minimal line-editing interface used by the REPL.
    • Exposes the local editing, history, and completion hooks needed by talk.

  • src/talk/linenoise.cpp

    • Local implementation of the lightweight line editor.
    • Handles interactive terminal input, command history, Ctrl-C and Ctrl-D behavior, and tab completion integration.

Runtime Flow​

At a high level, the flow looks like this:

  1. entry.cpp validates the requested target endpoint.
  2. It constructs an HLQueryCLI instance pointing at http://host:port.
  3. It creates a TalkState object to remember the current shell context.
  4. It enters the readline-style loop provided by linenoise.cpp.
  5. Each input line is forwarded to ExecuteTalkCommand(...) in the src/talk implementation.
  6. That command handler translates the shell command into CLI calls, which then hit the daemon HTTP API.

This is why talk feels interactive, but it is still fundamentally a thin shell on top of the same HTTP-driven CLI layer used elsewhere in the project.

SQL in talk​

Prefix SQL with sql:. The statement is sent to the daemon /sql route, so the collection comes from the FROM clause and does not depend on the active REPL context. For write-oriented SQL, talk also accepts exec: and exec <statement> as aliases.

Examples:

localhost:9200> sql: SELECT * FROM products LIMIT 3;
localhost:9200> sql: SELECT COUNT(*) AS total_docs FROM products;
localhost:9200> sql: SELECT AVG(score) AS avg_score FROM products;
localhost:9200> sql: SELECT category, COUNT(*) AS total_docs FROM products GROUP BY category ORDER BY total_docs DESC LIMIT 10;
localhost:9200> sql: SELECT category, AVG(score) AS avg_score FROM products GROUP BY category ORDER BY avg_score DESC;
localhost:9200> exec: INSERT INTO products (id, title, price) VALUES ("prod_10", "Keyboard", 49.99);
localhost:9200> exec "SELECT * FROM products LIMIT 3;"

SQL Notes​

  • SELECT * returns document-style hits.
  • Aggregate-only queries such as COUNT(*), AVG(score), MIN(price), and MAX(price) render as aggregation tables.
  • Grouped aggregate queries return row-oriented tables.
  • sql: currently supports SELECT, INSERT, and DELETE statements in the REPL.
  • exec: is an alias for SQL execution in talk, and exec "SELECT * FROM products;" works the same as sql: SELECT * FROM products;.
  • Quoted exec input is unwrapped once by the REPL, so exec "SELECT * FROM products;" is valid, but exec by itself only shows usage.
  • End statements with ; to match the examples and keep copy/paste predictable.

Useful REPL Commands​

help
ls
use products
search "wireless mouse" 5 0 price:desc --fields=title,price
sql: SELECT COUNT(*) AS total_docs FROM products;
sql: SELECT brand, AVG(price) AS avg_price FROM products GROUP BY brand ORDER BY avg_price DESC;
stats
ping
exit

Engine and I/O​

lsm​

Show deep engine statistics.

hlquery-cli lsm

dbsize​

Show on-disk size.

hlquery-cli dbsize
hlquery-cli dbsize gb

tx​

Show processed bytes.

hlquery-cli tx
hlquery-cli tx mb

Distributed and AI Helpers​

Inspect configured distributed links.

hlquery-cli links
hlquery-cli links ping

ask​

Ask a natural-language question, optionally scoped to a collection.

hlquery-cli ask books "what is this collection about?"
hlquery-cli ask "what collections are available?" 3 1

API Keys​

hlquery-cli keys list
hlquery-cli keys create --desc="Public search" --cols=products --actions=search
hlquery-cli keys update <id> --actions=search,create
hlquery-cli keys delete <id>

Dangerous Operations​

flush​

Delete all collections and data.

hlquery-cli flush --force

Only use this against disposable environments.

Common Workflows​

Inspect a server​

hlquery-cli health
hlquery-cli stats
hlquery-cli cols
hlquery-cli doctotal

Create a collection and search it​

hlquery-cli create products title content price category
hlquery-cli add products p1 "Product 1" "Description" price=99.99 category=electronics
hlquery-cli search products "electronics" 10
hlquery-cli open products/p1 --json

Run consistency checks​

hlquery-cli doctotal
hlquery-cli verify
hlquery-cli rebuild-counters products --index

Troubleshooting​

ProblemLikely causeWhat to run
Unknown commandStale docs or old muscle memoryhlquery-cli help
Connection failedServer not running or wrong URLhlquery-cli --url http://localhost:9200 health
Auth errorsMissing or wrong tokenhlquery-cli --auth <token> stats
Need raw endpoint outputPretty output hides fields you wanthlquery-cli --raw stats

Next Steps​