PAVEDB
Documentation
Version 0.9.7

🛣️ PaveDB CLI Reference

Command reference for pavecli, the local PaveDB administration and data-loading tool.

Generated from pave.cli.build_parser. Regenerate with make docs-refresh.

Common Flow

pavecli init
pavecli create-collection demo/books
pavecli ingest demo/books ./book.txt --docid book-1
pavecli search demo/books "captain nemo" -k 3

Usage

pavecli [-h] [--compact] [--version] [--home HOME]
        [--config CONFIG]
        [--tenants TENANTS] [--data-dir DATA_DIR] <command> ...

Pre-1.0 Note

Runtime selectors (–home, –config, –tenants, –data-dir) are global options. Pass them before the command, e.g. pavecli –home ./instance list-tenants. Store commands open the local data directory directly. They refuse to run while another PaveDB process owns it.

PaveDB 0.9.7 (pavecli) Copyright (C) 2025, 2026 Rodrigo Rodrigues da Silva rodrigo@flowlexi.com There is NO WARRANTY, to the extent permitted by law.

Global Options

  • --compact (optional): Emit compact JSON for scripting
  • --version (optional): Print version, copyright, and license information
  • --home (optional): Instance home directory; omitted siblings default under it; defaults to ~/pavedb
  • --config (optional): Explicit config.yml path; default comes from PAVEDB_CONFIG/config search
  • --tenants (optional): Explicit tenants.yml path; default comes from PAVEDB_AUTH__TENANTS_FILE/config
  • --data-dir (optional): Explicit data directory; default comes from PAVEDB_DATA_DIR/config

Commands

CommandDescription
initCreate a PaveDB instance config and data directory.
adminManage the local admin key.
create-collectionCreate a collection.
ingestIndex a file into a collection.
ingest-batchIndex raw-text documents into a collection.
ingest-textIndex raw text into a collection.
searchSearch a collection.
list-queriesList logged query IDs.
get-queryFetch a logged query by ID.
replay-queryReplay a logged query by ID.
list-documentsList documents in a collection.
get-documentFetch one document by ID.
list-chunksList chunks for a document.
get-chunkFetch chunk metadata.
get-chunk-contentPrint raw chunk text.
delete-collectionDelete a collection.
move-collectionMove a collection to a new name.
update-collectionUpdate collection metadata.
delete-documentDelete a document by ID.
dump-archiveExport the instance, or one collection, as an archive.
restore-archiveRestore the instance, or one collection, from an archive.
reset-metricsReset persisted metrics.
list-tenantsList tenants with cataloged collections.
list-embeddersList configured embedder instances.
list-collectionsList collections for a tenant.
get-collectionFetch collection details.

init

Create config.yml, tenants.yml, and the data directory for an instance.

Usage

pavecli init [-h] [--force] [root]

Examples

pavecli init
pavecli init ~/pavedb-staging
pavecli --config /etc/pavedb/config.yml \
  --tenants /var/pavedb/tenants.yml \
  --data-dir /var/pavedb/data init

Arguments And Options

  • root (optional): Instance home directory
  • --force (optional): Overwrite config and tenants files if they already exist

admin

Show or rotate the local instance admin key.

Usage

pavecli admin [-h] {show-key,rotate-key} ...

Examples

pavecli admin show-key
pavecli admin rotate-key

Arguments And Options

  • admin_cmd (required): (choices: show-key, rotate-key)

create-collection

Create a collection, optionally with display and embedder configuration.

Usage

pavecli create-collection [-h] [--display-name DISPLAY_NAME]
                                 [--embedder EMBEDDER]
                                 [--embedder-type EMBEDDER_TYPE]
                                 [--embed-model EMBED_MODEL]
                                 [--embedder-config EMBEDDER_CONFIG]
                                 [--search-mode {vector,boost,hybrid}]
                                 [--priority-key PRIORITY_KEY]
                                 [--chunking CHUNKING]
                                 tenant/collection

Example

pavecli create-collection demo/books --display-name "Books"

Arguments And Options

  • tenant/collection (required): Tenant and new collection, e.g. demo/books. The collection slug takes lowercase letters, digits, and hyphens; must start with a letter or digit; max 63 chars
  • --display-name (optional): Human-readable collection label
  • --embedder (optional): Configured embedder selector: instance key, type, type:model, or full vector-space key
  • --embedder-type (optional): Embedder type, such as sbert, openai, or ollama
  • --embed-model (optional): Embedding model name
  • --embedder-config (optional): JSON object with embedder-specific config
  • --search-mode (optional): Default ranking mode for searches that name none (vector) (choices: vector, boost, hybrid)
  • --priority-key (optional): Metadata field whose value in [-1, 1] scales scores by (1
    • value); omitted: prio_boost
  • --chunking (optional): JSON object, e.g. {“strategy”:“fixed”,“size”:800,“overlap”:100} or {“strategy”:“none”}; omitted fields take the instance default

ingest

Preprocess and index a TXT, CSV, or PDF file into a collection.

Usage

pavecli ingest [-h] [--docid DOCID] [--metadata METADATA]
                      [--csv-has-header {auto,yes,no}]
                      [--csv-meta-cols CSV_META_COLS]
                      [--csv-include-cols CSV_INCLUDE_COLS]
                      tenant/collection file

Example

pavecli ingest demo/books ./book.txt --docid book-1 --metadata '{"lang":"en"}'

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • file (required): Path to TXT, CSV, or PDF input
  • --docid (optional): Stable document ID; defaults from filename when omitted
  • --metadata (optional): JSON object attached to the document
  • --csv-has-header (optional): CSV header handling: auto, yes, or no (choices: auto, yes, no)
  • --csv-meta-cols (optional): CSV columns for metadata only (not indexed). Names or 1-based indices, comma-separated
  • --csv-include-cols (optional): CSV columns to index. Names or 1-based indices, comma-separated. Defaults to all non-meta columns

ingest-batch

Index a JSON batch of raw-text documents.

Usage

pavecli ingest-batch [-h] tenant/collection file

Example

pavecli ingest-batch demo/books ./documents.json

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • file (required): JSON batch input file

ingest-text

Index one raw-text document.

Usage

pavecli ingest-text [-h] [--docid DOCID] [--metadata METADATA]
                           tenant/collection text

Example

pavecli ingest-text demo/books "Captain Nemo" --docid note-1

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • text (required): Raw text to index
  • --docid (optional): Stable document ID; generated when omitted
  • --metadata (optional): JSON object attached to the document

Run ranked search over a collection and print the response envelope.

Usage

pavecli search [-h] [-k K] [--mode {vector,boost,hybrid}]
                      [--include-common] [--filters FILTERS]
                      [--content-filter CONTENT_FILTER]
                      tenant/collection query

Example

pavecli search demo/books "captain nemo" -k 3

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • query (required): Natural-language search query
  • -k (optional): Number of matches to return (default: 5)
  • --mode (optional): Ranking mode; defaults to the collection’s search mode (choices: vector, boost, hybrid)
  • --include-common (optional): Include configured common collection results
  • --filters (optional): JSON object, e.g. {“docid”:“DOC-1”}
  • --content-filter (optional): JSON object with op exact, phrase, prefix, or contains and a non-empty value

list-queries

List logged query IDs, optionally scoped to a tenant or collection.

Usage

pavecli list-queries [-h] [--tenant TENANT] [--collection COLLECTION]
                            [--limit LIMIT] [--offset OFFSET]

Example

pavecli list-queries --tenant demo --collection books --limit 20

Arguments And Options

  • --tenant (optional): Filter by tenant
  • --collection (optional): Filter by collection
  • --limit (optional): Maximum entries to return (default: 50)
  • --offset (optional): Entries to skip

get-query

Resolve a query_id through the catalog and print the stored query log entry.

Usage

pavecli get-query [-h] query_id

Example

pavecli get-query 6f7cfd26-7d7f-4e5d-942b-f2a516f515a6

Arguments And Options

  • query_id (required): Query ID to fetch

replay-query

Resolve a query_id through the catalog and run the stored query again.

Usage

pavecli replay-query [-h] query_id

Example

pavecli replay-query 6f7cfd26-7d7f-4e5d-942b-f2a516f515a6

Arguments And Options

  • query_id (required): Query ID to replay

list-documents

Print indexed documents and their collection metadata.

Usage

pavecli list-documents [-h] tenant/collection

Example

pavecli list-documents demo/books

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books

get-document

Print document metadata and chunk summary for one document.

Usage

pavecli get-document [-h] tenant/collection docid

Example

pavecli get-document demo/books book-1

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • docid (required): Document ID

list-chunks

Print chunk metadata for a document without chunk text content.

Usage

pavecli list-chunks [-h] tenant/collection docid

Example

pavecli list-chunks demo/books book-1

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • docid (required): Document ID

get-chunk

Print metadata for one chunk by record ID.

Usage

pavecli get-chunk [-h] tenant/collection rid

Example

pavecli get-chunk demo/books book-1::chunk_0

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • rid (required): Chunk record ID

get-chunk-content

Write one chunk’s text content to stdout.

Usage

pavecli get-chunk-content [-h] tenant/collection rid

Example

pavecli get-chunk-content demo/books book-1::chunk_0

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • rid (required): Chunk record ID

delete-collection

Remove a collection, including its local metadata and vector index.

Usage

pavecli delete-collection [-h] tenant/collection

Example

pavecli delete-collection demo/books

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books

move-collection

Rename the collection slug and move its catalog/query-home records.

Usage

pavecli move-collection [-h] tenant/collection tenant/new-collection

Example

pavecli move-collection demo/old-books demo/books

Arguments And Options

  • tenant/collection (required): Tenant and current collection, e.g. demo/old
  • tenant/new-collection (required): Same tenant and the new collection slug: lowercase letters, digits, and hyphens; must start with a letter or digit; max 63 chars

update-collection

Update collection metadata such as the display name, without re-indexing.

Usage

pavecli update-collection [-h] --display-name DISPLAY_NAME
                                 tenant/collection

Example

pavecli update-collection demo/books --display-name "Books"

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • --display-name (required): New human-readable collection label

delete-document

Remove one document and its chunks from a collection.

Usage

pavecli delete-document [-h] tenant/collection docid

Example

pavecli delete-document demo/books book-1

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books
  • docid (required): Document ID

dump-archive

Offline only; stop the server before reading its data directory. With tenant/collection, writes that collection as a portable archive. Without it, writes the whole instance; collections that fail validation are left out and listed under ‘skipped’, and the command exits non-zero.

Usage

pavecli dump-archive [-h] [--output OUTPUT] [tenant/collection]

Examples

pavecli dump-archive --output pavedb-data.zip
pavecli dump-archive demo/books --output books.zip

Arguments And Options

  • tenant/collection (optional): Collection to export; omit for the instance
  • --output (optional): Destination ZIP file path

restore-archive

Offline only; stop the server first. With tenant/collection, creates that collection from a same-version collection archive, or with –replace overwrites the existing one. Without it, replaces the data directory from an instance archive.

Usage

pavecli restore-archive [-h] [--replace] [tenant/collection] file

Examples

pavecli restore-archive pavedb-data.zip
pavecli restore-archive demo/books books.zip

Arguments And Options

  • tenant/collection (optional): Destination collection; omit for an instance archive
  • file (required): Archive zip file path
  • --replace (optional): Overwrite an existing collection instead of creating it

reset-metrics

Clear the shared runtime metrics in the configured catalog database.

Usage

pavecli reset-metrics [-h]

Example

pavecli reset-metrics

list-tenants

Print tenants currently present in the collection catalog.

Usage

pavecli list-tenants [-h]

Example

pavecli list-tenants

list-embedders

Print configured embedder instances and the resolved default routing pool.

Usage

pavecli list-embedders [-h] [--tenant TENANT]

Examples

pavecli list-embedders
pavecli list-embedders --tenant demo

Arguments And Options

  • --tenant (optional): Tenant namespace to echo in the response

list-collections

Print collection names, display labels, and embedder labels for a tenant.

Usage

pavecli list-collections [-h] tenant

Example

pavecli list-collections demo

Arguments And Options

  • tenant (required): Tenant namespace

get-collection

Print catalog, embedder, vector-space, document, and chunk details for a collection.

Usage

pavecli get-collection [-h] tenant/collection

Example

pavecli get-collection demo/books

Arguments And Options

  • tenant/collection (required): Tenant and collection, e.g. demo/books