CLI usage

This page walks through everyday usage: confirming connectivity, working with indices and documents, searching, and the conventions that make the CLI script-friendly. It assumes you've already configured a context.

Quickstart

Confirm connectivity

lucenia ping

List indices

lucenia get indices
# or equivalently:
lucenia indices list

Search

lucenia search query -i logs -q 'level:error' --size 5

Pipe to jq — the CLI emits compact JSON automatically when its output isn't a terminal:

lucenia search query -i logs -q 'level:error' | jq '.hits.total.value'

The command tree

Commands are grouped by the resource they act on. Some common entry points:

Group	Examples
cluster	lucenia cluster health, lucenia cluster stats
indices	lucenia indices create logs --shards 3, lucenia indices delete logs
doc	lucenia doc index --index logs --file @event.json, lucenia doc get
search	lucenia search query, lucenia search count, lucenia search msearch
cat	lucenia cat shards, lucenia cat nodes
snapshot	lucenia snapshot create, lucenia snapshot restore
config	lucenia config set-context, lucenia config use-context

Kubectl-style verbs work across resources too — lucenia get indices and lucenia describe index logs mirror the typed forms.

Typed commands vs. raw

Typed commands (lucenia indices list, lucenia cluster health, …) are the default. They validate flags, render tables on a TTY, and map HTTP status to exit codes. Use lucenia raw when you need an endpoint the typed tree doesn't cover yet, or when you want unfiltered server output.

Typed	Equivalent raw
lucenia ping	lucenia raw GET /
lucenia cluster health	lucenia raw GET /_cluster/health
lucenia indices list	lucenia raw GET /_cat/indices -Q format=json
lucenia indices create logs --shards 3	lucenia raw PUT /logs --data '{"settings":{...}}'
lucenia indices delete logs --yes	lucenia raw DELETE /logs --yes
lucenia doc index --index logs --file @e.json	lucenia raw POST /logs/_doc --file @e.json
lucenia search query -i logs -q 'foo'	lucenia raw POST /logs/_search --data '{...}'
lucenia cat shards	lucenia raw GET /_cat/shards -Q format=json

Prefer the typed form when it exists — it picks better defaults (table on a TTY, JSON when piped, status colorization, exit-on flags) and stays compatible if the underlying REST shape changes.

Output formats

The -o flag controls rendering:

• -o auto (default) — JSON when piped, a table or sectioned text on a TTY.
• -o json — always JSON.
• -o table — always a table.

Color is honored unless NO_COLOR is set in the environment.

Destructive commands

Commands that delete or overwrite data prompt for confirmation. Pass --yes to skip the prompt in scripts:

lucenia indices delete logs --yes

Exit codes

The CLI returns deterministic exit codes so scripts can branch on the outcome rather than parsing output. 0 is success; non-zero codes distinguish usage errors, transport failures, authentication problems, not-found, conflict, and unhealthy-cluster conditions. This makes the CLI safe to use in pipelines and CI gates.

Verbosity and request IDs

Increase verbosity to inspect what the client is doing on the wire:

lucenia -v   cluster health   # URL, method, status, latency
lucenia -vv  cluster health   # + request/response headers
lucenia -vvv cluster health   # + bodies (warns past 1 MB)

Set defaults.request_id: true in the config to stamp every request with an X-Opaque-Id: lucenia-cli/<ulid> header for log correlation on the server side.

Shell completion

Generate a completion script for your shell:

lucenia config completion bash   # or zsh, fish, powershell

Completion includes dynamic context names and (best-effort, with a 1-second timeout) live index names pulled from the cluster, so lucenia <TAB> is also a way to explore the API surface. See the generated lucenia config completion reference for per-shell installation snippets.

Full command reference

A complete, generated reference for every command and flag lives in the docs/cli/ directory of the CLI repository, starting at lucenia.md. You can also discover any command's flags inline:

lucenia --help
lucenia search query --help