CLI reference

yolosearch serves an index, reads and changes a running server's settings, shows its statistics, and builds and publishes the immutable segments it reads.

The commands fall into three families, and which family a command belongs to decides where it gets its configuration:

explain parses and lowers locally; with --index, it fetches the schema from the server.

This page reproduces the command tree and each command's own flags. It does not repeat the several dozen configuration-backed flags that serve, node, and the offline verbs share — those are in the configuration reference, which lists the key, the flag, and the environment variable for each one together.

Every command accepts these. Each is backed by a setting, so a file or an environment variable can set it too.

yolosearch serve [SOURCE_URL] [flags]

Hosts every index under the object root — or exactly one with --index — and answers SearchService, IngestService, IndexService, CatalogService, AdminService, and ConfigService for them.

An empty object root is a valid start: schema apply creates an index while serving, push fills it, and each index follows the catalog so a published generation is served without a restart. The listening= line on stdout says where it serves once every hosted index is resolved and the socket is bound.

With --checkpoint it answers SearchService and ConfigService only.

yolosearch serve --data-dir ./ys --listen 127.0.0.1:9500
yolosearch serve --index demo --listen 127.0.0.1:9500 \
  --cache-dir ./cache --ingest-dir ./ingest --object-dir ./objects
yolosearch --config ys.yml serve
yolosearch serve s3://search-data/production/indexes/articles/

The positional SOURCE_URL sets object.source, which attaches a dataset read-only. See object store.

yolosearch node [flags]

Serves any combination of the query-fleet roles plus the maintenance-only compactor role from one process. Catalog-bound roles resolve their generation before the listener opens, so a node that cannot read its catalog fails at startup rather than accepting work it cannot perform.

A dedicated compactor opens no query engine or full-segment cache; it follows latest and performs single-flight copy-on-write physical merges under the compaction budgets.

node has no flags of its own — every flag is a configuration-backed one. The ones that decide topology:

yolosearch node --roles aggregator --listen 127.0.0.1:9601
yolosearch node --roles worker --listen 127.0.0.1:9602 --index demo \
  --object-dir ./objects --cache-dir ./cache --aggregators 127.0.0.1:9601
yolosearch node --roles compactor --listen 127.0.0.1:9701 --index demo \
  --object-dir ./objects --ingest-dir ./scratch

yolosearch search <index> <query> [flags]

Parses a Lucene or CQP query, lowers it to the structured request the server executes, and prints the hits — collapsed by key by default. Lowering happens client-side, so a typo lands a caret before any round trip.

Result shape

--keys and --ids are line-oriented streaming modes for large result sets. --ids requests no stored documents and no scores, which is the cheapest machine-readable output.

Vector and hybrid

Approximate tail

yolosearch search articles 'title:http AND body:"status code"'
yolosearch search articles '[word="colou?r"] []{0,3} [word="blind"]' \
  --dialect cqp --fields title,url
yolosearch search articles 'quantum' --vector-field embedding \
  --vector-text 'quantum computing' --fusion rrf

yolosearch explain <query> [flags]

Parses a query and prints its AST, its stable digest, the schema it lowered against, the lowered structured query, and its filters — without touching an index.

Without --index the assumed schema is used: every named field is indexed, and word is every indexed field. --json prints the same as a nested object.

yolosearch push <index> <files...|-> [flags]

Reads JSONL, a JSON array, or a single JSON object — auto-detected — validates each document against the index's schema, converts it to a typed document, and streams the batches to the server.

Unless --no-flush, it flushes and waits for the segment to publish, printing the sealed segment and generation. A file holding one pretty-printed object is one document; a file of one-line objects is one document per line.

To load compressed files or archives without uncompressing them first, use the admin console's Ingest section.

yolosearch delete <index> <keys...|-> [flags]

Tombstones each given key: that key's current version is superseded by nothing, and it stops appearing in results without invalidating the rest of the index.

Keys are given as arguments, or read one per line from stdin when the sole argument is -. Deleting a key that does not exist is not an error: delete is idempotent.

yolosearch schema apply [file] [flags]

Sends a schema to the server's IndexService: a .proto compiled in-process, a descriptor set (.binpb), or an authored schema (.yaml, .json, .textproto).

The index is the one the .proto's (yolosearch.v1.document) option declares, or --index. An index that does not exist is created at version 1; re-applying an unchanged schema is a no-op; an additive change mints the next version; anything else is refused with the diff.

yolosearch schema diff [file] [flags]

Renders the change apply would make — the same table the server puts in a refusal — without writing anything. Exits 1 when the change is not additive.

Flags: --proto, --schema, --index, --message.

yolosearch schema show [flags]

yolosearch schema history [flags]

Lists every version of an index's schema. Takes --index.

yolosearch schema options [flags]

Prints the annotation .proto a document schema imports — the file providing yolosearch.v1.document and yolosearch.v1.field.

yolosearch schema propose <directory> [flags]

Infers an editable schema and normalized JSONL from local documents.

yolosearch index list [flags]

Names every index in the server's object root with its schema version and active generation.

yolosearch index describe <index> [flags]

Prints one index's header and its current schema.

yolosearch config get <key> [flags]

Shows one setting and where its value came from.

yolosearch config get ingest.seal_age
# ingest.seal_age = 5s (source: api)

yolosearch config list [flags]

Lists every setting with its value, scope, and source.

yolosearch config set <key> <value> [flags]

Overrides a node-runtime setting until unset or restart. Only settings whose scope is node-runtime accept it.

yolosearch config set log.level debug
yolosearch config set ingest.seal_age 5s

yolosearch config unset <key> [flags]

Drops a runtime override; the file, environment, or flag value returns.

yolosearch config watch [flags]

Prints every matching setting, then one line per change, until interrupted. Takes --prefix.

yolosearch config export [flags]

Resolves this process's own configuration offline and prints it. Unlike the other config verbs it dials no server.

These are offline verbs. They work on an object store directly and take the object.* settings rather than --server.

yolosearch catalog resolve [flags]

Prints the latest generation, or --generation, as the catalog records it.

yolosearch catalog publish [flags]

Announces a published segment, and converges the catalog on everything committed.

yolosearch catalog reconcile [flags]

Repairs the catalog's lineage from the committed segments without announcing anything new.

yolosearch catalog compact [flags]

Physically merges active immutable segments and atomically replaces them.

yolosearch catalog gc-dry-run [flags]

Proposes unreferenced objects against explicit retention horizons. Removes nothing.

yolosearch segment build [flags]

Builds one immutable segment from JSONL and writes its checkpoint to the object directory.

yolosearch segment build --schema schema.json --input docs.jsonl \
  --work-dir ./work --object-dir ./objects --checkpoint segments/demo

yolosearch segment publish [flags]

Publishes a built segment commit-last and announces it to the catalog.

yolosearch stats [<index>] [flags]

With no argument, lists every index the server's object root holds with the totals of its active generation; an index the node does not serve is named as such rather than shown empty. With an index, prints the detail and the head of the generation lineage.

Unreachable nodes in a --fleet frame are named, never zero-filled.

yolosearch stats
yolosearch stats articles --json
yolosearch stats --node --watch

yolosearch version [flags]

Prints the build identity — the same line as --version.

yolosearch manual [flags]

Renders the reference from the command tree and the configuration catalog, so it cannot drift from the binary.

yolosearch is one of five binaries. This page covers only it.

• Configuration reference — the settings behind most flags
• The Lucene grammar and the CQP grammar — what search accepts
• Ingest — what push and delete do on the server