Command-line reference

Every command of the quivr binary, from the tables the binary itself dispatches on, in internal/app/run.go (engine), internal/plugins/cli/cli.go (offline) and internal/online/online.go (online). The Needs column says whether a command runs the engine, works offline, or needs a running server. For the online commands in use, see Search from the command line; for AI agents, see Connect an AI agent and the MCP reference.

Commands

Command	Needs	Summary
`quivr api`	a configuration file (`QUIVR_CONFIG`)	Serve the public HTTP API until interrupted.
`quivr worker`	a configuration file (`QUIVR_CONFIG`)	Run the background work that processes content, pulls connectors and delivers events, until interrupted.
`quivr journal`	a configuration file (`QUIVR_CONFIG`)	Inspect change publication and explicitly switch its deployment-wide mode.
`quivr storage`	a configuration file (`QUIVR_CONFIG`)	Check PostgreSQL schema readiness and report compact storage.
`quivr migrate`	a configuration file (`QUIVR_CONFIG`)	Prepare PostgreSQL, object storage and the search projections, then exit. Rerun it to finish a step whose dependency was not ready.
`quivr --version`	nothing: works offline	Print build identity without configuration or a running server.
`quivr plugin dev`	nothing: works offline	Run a plugin locally, check its discovery against the manifest and replay a fixture; restarts it on change with `--watch`.
`quivr plugin init`	nothing: works offline	Write a new Python plugin from a template: a normalizer, an alert rule (`--kind subscription`) or a source collector (`--kind connector`; add `--push` for an instance-token push source).
`quivr plugin inspect`	nothing: works offline	Validate a plugin manifest and print what the plugin declares.
`quivr plugin test`	nothing: works offline	Certify that the engine can safely invoke every Contribution the plugin declares.
`quivr search`	a running server	Search one or more Corpora of a running Quivr and print ranked hits with their provenance.
`quivr records`	a running server	List one page of a Corpus’s Records or get a count, with optional time bounds. Prints the API JSON; list pages include a continuation cursor when another page exists.
`quivr mcp`	a running server	Serve Quivr to an AI agent over MCP on stdin and stdout, with the tools of one profile.
`quivr apply`	a running server	Preview or apply a private sources declaration through the public API.

Engine commands

Engine commands run Quivr itself and read the JSON configuration file named by QUIVR_CONFIG; api, worker and migrate connect to PostgreSQL, Temporal, object storage and Weaviate. api and worker run until interrupted; migrate exits when done. migrate --contract also applies deferred contract migrations and closes the application rollback window. api and worker take no flags. storage status and journal connect only to PostgreSQL. journal status reads publication progress; mode changes require the documented writer-drain acknowledgement.

Environment variable	Meaning
`QUIVR_CONFIG`	path of the JSON configuration file

Exit code	Meaning
0	stopped cleanly, or migrate finished
1	the process failed, or the command is unknown; the reason is logged as JSON on stderr
2	invalid command arguments

quivr api

Serve the public HTTP API until interrupted.

quivr api

quivr worker

Run the background work that processes content, pulls connectors and delivers events, until interrupted.

quivr worker

quivr journal

Inspect change publication and explicitly switch its deployment-wide mode.

quivr journal status
quivr journal activate --previous-writers-retired
quivr journal legacy --writers-drained
quivr journal restored --writers-drained

quivr storage

Check PostgreSQL schema readiness and report compact storage.

quivr storage status

quivr migrate

Prepare PostgreSQL, object storage and the search projections, then exit. Rerun it to finish a step whose dependency was not ready.

quivr migrate [--contract]

Offline commands

quivr --version prints the distribution release, revision, API version and plugin engine compatibility version. quivr plugin commands help write and certify a plugin. They need no configuration file and no running server. Run quivr plugin alone to list them.

Exit code	Meaning
0	success; for `test`, the plugin is certified
1	for plugin commands only: an invalid plugin or manifest, a target directory `init` cannot write, a plugin `dev` cannot start; for `test`, the plugin is not certified
2	invalid flags or arguments

quivr —version

Print build identity without configuration or a running server.

quivr --version

quivr plugin dev

Run a plugin locally, check its discovery against the manifest and replay a fixture; restarts it on change with --watch.

quivr plugin dev [--fixture <file>] [--watch] [--port <n>] [--startup-timeout <duration>] [<plugin-dir>]

quivr plugin init

Write a new Python plugin from a template: a normalizer, an alert rule (--kind subscription) or a source collector (--kind connector; add --push for an instance-token push source).

quivr plugin init <name> [--kind normalizer|subscription|connector] [--push] [--dir <path>]

quivr plugin inspect

Validate a plugin manifest and print what the plugin declares.

quivr plugin inspect [--json] <plugin-dir|quivr-plugin.yaml>

quivr plugin test

Certify that the engine can safely invoke every Contribution the plugin declares.

quivr plugin test [--endpoint <url>] [--report <file>] [--fixture <file>]... [--startup-timeout <duration>] [<plugin-dir>]

Online commands

Online commands reach a running Quivr through its public HTTP API only, with an API key. They need no configuration file. Each prints its flags, environment and exit codes with --help, shown below.

Environment variable	Meaning
`QUIVR_API_URL`	base URL of the Quivr API; `--api-url` overrides it
`QUIVR_API_KEY`	API key sent as a bearer token; `--api-key` overrides it

quivr search

Search one or more Corpora of a running Quivr and print ranked hits with their provenance. quivr search --help prints:

usage: quivr search --corpus <corpus-id> [--corpus <corpus-id>]... [--mode lexical|semantic|hybrid] [--profile <name>] [--limit <1-50>] [--source <namespace>]... [--json] [--api-url <url>] [--api-key <key>] <query>

Search one or more Corpora of a running Quivr and print ranked hits with their provenance.

Flags:
  -api-key string
    	API key sent as a bearer token (default $QUIVR_API_KEY)
  -api-url string
    	Quivr API base URL (default $QUIVR_API_URL)
  -corpus value
    	Corpus ID to search; repeat or separate with commas (required)
  -json
    	print the public API response unchanged
  -limit int
    	maximum number of hits, 1 to 50 (server default: 10)
  -mode string
    	search mode: lexical, semantic or hybrid (server default: hybrid)
  -profile string
    	search profile name, as GET /v0/search/profiles lists them (server default: default)
  -source value
    	keep only Records from this Source Namespace, ranked among themselves; repeat or separate with commas

This command needs a running Quivr server. It reads the server address from
QUIVR_API_URL and the API key from QUIVR_API_KEY; --api-url and --api-key
override them. It talks to the server only through its public HTTP API.

Exit codes:
  0  success
  1  unexpected failure
  2  invalid arguments, or a missing or malformed API URL
  3  API key rejected, or not allowed on a requested resource (401, 403)
  4  request rejected as invalid (400, 404, 409, 422)
  5  server unreachable or unavailable (connection error, timeout, 5xx)
  130  interrupted

quivr records

List one page of a Corpus’s Records or get a count, with optional time bounds. Prints the API JSON; list pages include a continuation cursor when another page exists. quivr records --help prints:

usage: quivr records --corpus <corpus-id> [--order record_id|accepted_at_desc] [--accepted-after <RFC3339>] [--accepted-before <RFC3339>] [--page-cursor <cursor>] [--limit <1-100>] [--count] [--api-url <url>] [--api-key <key>]

List one page of a Corpus's Records or get a count, with optional time bounds. Prints the API JSON; list pages include a continuation cursor when another page exists.

Flags:
  -accepted-after string
        inclusive current-Version acceptance time, RFC 3339 with an offset, at most 9 fractional digits
  -accepted-before string
        exclusive current-Version acceptance time, RFC 3339 with an offset, at most 9 fractional digits
  -api-key string
        API key sent as a bearer token (default $QUIVR_API_KEY)
  -api-url string
        Quivr API base URL (default $QUIVR_API_URL)
  -corpus string
        Corpus ID (required; needs content:read)
  -count
        print a count (large unbounded counts are approximate); omit order, page-cursor and limit
  -limit int
        page size, 1 to 100 (default 100)
  -order string
        record_id for resynchronization (default), or accepted_at_desc for newest current Versions first
  -page-cursor string
        next_page_cursor from the preceding response; repeat its order and bounds

This command needs a running Quivr server. It reads the server address from
QUIVR_API_URL and the API key from QUIVR_API_KEY; --api-url and --api-key
override them. It talks to the server only through its public HTTP API.

Exit codes:
  0  success
  1  unexpected failure
  2  invalid arguments, or a missing or malformed API URL
  3  API key rejected, or not allowed on a requested resource (401, 403)
  4  request rejected as invalid (400, 404, 409, 422)
  5  server unreachable or unavailable (connection error, timeout, 5xx)
  130  interrupted

quivr mcp

Serve Quivr to an AI agent over MCP on stdin and stdout, with the tools of one profile. quivr mcp --help prints:

usage: quivr mcp --profile read|ingest [--api-url <url>] [--api-key <key>]

Serve Quivr to an AI agent over MCP on stdin and stdout, with the tools of one profile.

Flags:
  -api-key string
    	API key sent as a bearer token (default $QUIVR_API_KEY)
  -api-url string
    	Quivr API base URL (default $QUIVR_API_URL)
  -profile string
    	tool profile to serve (required): read|ingest

Profiles:
  read  list reachable Corpora, search them and read Records; no tool changes data
    list_corpora  List reachable Corpora
    search  Search Corpora
    read_record  Read a Record
  ingest  the read tools, plus ingest text into a Corpus and follow its Ingestion Receipt; no tool withdraws or deletes
    list_corpora  List reachable Corpora
    search  Search Corpora
    read_record  Read a Record
    ingest_text  Ingest text into a Corpus
    read_receipt  Read an Ingestion Receipt

This command needs a running Quivr server. It reads the server address from
QUIVR_API_URL and the API key from QUIVR_API_KEY; --api-url and --api-key
override them. It talks to the server only through its public HTTP API, and
the API key decides which Corpora every tool may reach.

An MCP client starts it and speaks JSON-RPC on stdin and stdout; diagnostics go
to stderr. A refused or failed API call is returned to the agent as a tool
error carrying the public error code, such as forbidden or unreachable. When
stdin closes, it waits up to a minute to answer the requests already received,
then exits.

Exit codes:
  0  the client closed the connection, and every request was answered
  1  unexpected failure, or requests still unanswered a minute after stdin closed
  2  invalid arguments, or a missing or malformed API URL
  130  interrupted

quivr apply

Preview or apply a private sources declaration through the public API. quivr apply --help prints:

quivr apply -f sources.json [--state-file journal.json] [--confirm]
  -api-key string
        API key sent as a bearer token (default $QUIVR_API_KEY)
  -api-url string
        Quivr API base URL (default $QUIVR_API_URL)
  -confirm
        execute the displayed changes (default: preview only)
  -f string
        JSON sources declaration
  -operator-key-env string
        environment reference for plugin administration (default "QUIVR_OPERATOR_KEY")
  -state-file string
        private replay journal (default <declaration>.state.json)
This command needs a running Quivr server. It reads the server address from
QUIVR_API_URL and the API key from QUIVR_API_KEY; --api-url and --api-key
override them. It talks to the server only through its public HTTP API.

Exit codes:
  0  success
  1  unexpected failure
  2  invalid arguments, or a missing or malformed API URL
  3  API key rejected, or not allowed on a requested resource (401, 403)
  4  request rejected as invalid (400, 404, 409, 422)
  5  server unreachable or unavailable (connection error, timeout, 5xx)
  130  interrupted

Quivr 2

HTTP API

Endpoints

Command line

Plugins

Deployment