CLI Reference

The indx command line has three core operations: build, inspect, and query. Build is the bare indx <dir> --out invocation — there is no build keyword. All three run over the same pipeline and data model as the SDK. A fourth command, app, launches a local web UI and ships in the optional indx[app] extra.

This page documents every flag, the stdout shapes, and all exit codes.

Install with pip install indx (Python 3.11–3.13). For the programmatic equivalent of every command, see the SDK reference.

Synopsis

indx <dir> --out <dir> [--config indx.toml] [options]   # build a knowledge space
indx inspect <archive.indx> [options]                    # summarize an archive
indx query   <archive.indx> "<text>" [options]           # semantic search
indx app [options]                                       # launch the local web UI (needs indx[app])
indx mcp <archive.indx> [options]                        # serve a space to AI agents over MCP (needs indx[mcp])

CLI ⇄ SDK parity

Every command maps to an SDK call. indx <dir> --out <dir> is DirectoryPipeline(...).run(src, out). indx query is space.search(query, k=...). indx inspect reads space.stats and space.documents(type=...). Anything you can do at the terminal you can do in code, and vice versa.

indx <dir> — build

Process a directory (or a .zip) through the six-stage pipeline and write an AI-ready knowledge space to --out. The output directory receives the handbook.indx archive plus the expanded index.json, chunks/, and embeddings/ layout.

Build is the implicit default subcommand — there is no indx build keyword. Passing a directory (or .zip) as the first positional triggers a build. inspect and query are the only named subcommands.

The default stack reaches the cloud

The zero-config defaults are openai:gpt-5-mini for enrichment and openai:text-embedding-3-small for embeddings. They need OPENAI_API_KEY set, plus a reachable Qdrant (which runs embedded by default). For a run with no network and no optional backends, pass --offline or spell out the core combo: --parser plaintext --llm none --vlm none --embedder hash --store jsonl --format .indx. See the configuration reference and errors and exit codes.

Flags

Flag	Type	Default	Description
<dir> (positional)	path	— (required)	Directory or .zip to process.
--out, -o	path	— (required)	Output directory; receives handbook.indx, index.json, chunks/, embeddings/.
--config, -c	path	./indx.toml if present	Configuration file. See the configuration reference.
--parser	str	docling	Override the parser engine.
--llm	str	openai:gpt-5-mini	Override the enrichment LLM (none to disable, ollama:qwen2.5 for local).
--vlm	str	none	Override the vision model.
--embedder	str	openai:text-embedding-3-small	Override the embedder (bge-m3 for local).
--store	str	qdrant	Override the vector store backend.
--format	str	indx	Output writer: indx, jsonl, langchain, or llamaindex (the .indx is the sealed archive’s file extension; the writer name is indx).
--name	str	handbook	Archive base name (produces handbook.indx).
--strict	flag	off	Promote per-item skips to fatal failures.
--resume	flag	off	Reuse cached stage outputs for unchanged files and config.
--dry-run	flag	off	Walk only and print the build plan (files, folders, selected components); run no models and write nothing. Exits 0.
--offline	flag	off	Fill unset slots with the zero-dependency offline stack: plaintext, none, none, hash, jsonl, .indx. Explicit flags still win.
--aws	flag	off	Fill unset slots with the AWS managed stack: textract parser, bedrock LLM/VLM/embedder, s3vectors store. Requires pip install "indx[aws]". Mutually exclusive with --azure, --gcp, and --offline.
--azure	flag	off	Fill unset slots with the Azure managed stack: docintel parser, azure LLM/VLM/embedder, azure-search store. Requires pip install "indx[azure]". Mutually exclusive with --aws, --gcp, and --offline.
--gcp	flag	off	Fill unset slots with the GCP managed stack: docai parser, vertex LLM/VLM/embedder, bigquery store. Requires pip install "indx[gcp]". Mutually exclusive with --aws, --azure, and --offline.
--json	flag	off	Emit a machine-readable build summary with counts, components, elapsed time, and per-stage timings.
--jobs, -j	int	CPU count	Parallel workers for parse/embed.
--no-embed	flag	off	Skip stage 06 vectorization (produce a graph-only space).
--quiet / --verbose	flag	normal	Decrease / increase log verbosity.

Component overrides resolve by precedence

For each component slot the effective value is chosen in this order: explicit CLI flag, then indx.toml, then the documented default. So --store chroma beats a [store] table in your config, which in turn beats the qdrant default. See the configuration reference for the full precedence rules.

Output

By default the build prints one progress line per stage, then a summary:

indx ./docs → ./ai-ready
  01 walk    128 files, 14 folders
  02 parse   128 ok, 0 skipped
  03 chunk   1042 chunks
  04 relate  380 relations
  05 enrich  128 documents (openai:gpt-5-mini)
  06 embed   1042 vectors → qdrant, sealed handbook.indx
done: 1042 chunks, 128 docs, embed_dim=1536  (12.4s)

--quiet suppresses the per-stage lines, but the summary still prints. --verbose adds detail such as per-stage cache hits and misses when --resume is active.

Fully offline builds

Pass --offline for the zero-dependency core stack. It selects --parser plaintext --llm none --vlm none --embedder hash --store jsonl --format .indx for any slot you did not set yourself. The hash embedder is deterministic and offline, but it is lexical rather than a semantic model. See the air-gapped guide.

Single-vendor cloud builds

--aws, --azure, and --gcp are sibling presets that work exactly like --offline: they fill every slot you did not set explicitly, leaving your explicit flags untouched.

indx ./docs --out ./ai-ready --aws             # Textract → Bedrock → Titan → S3 Vectors
indx ./docs --out ./ai-ready --azure           # Doc Intelligence → Azure OpenAI → Azure AI Search
indx ./docs --out ./ai-ready --gcp             # Document AI → Gemini → gemini-embedding-001 → BigQuery
indx ./docs --out ./ai-ready --aws --store qdrant  # AWS stack but with Qdrant as the store

Each preset is mutually exclusive with the others and with --offline — passing two raises a usage error (exit 2). Credentials come from each cloud’s native environment; see the extras reference for the credential models and required extras.

SDK equivalent:

from indx import DirectoryPipeline

space = DirectoryPipeline(
    parser="docling",
    llm="openai:gpt-5-mini",
    embedder="openai:text-embedding-3-small",
    store="qdrant",
).run("./docs", "./ai-ready")

The --strict flag corresponds to strict=True in the SDK. --no-embed corresponds to dropping the embed-pack stage (pipeline.drop("embed-pack")). Full details are in the SDK reference.

indx inspect <archive.indx>

Summarize a sealed .indx archive without re-running the pipeline. By default it prints space stats, a document-type histogram, and a sample of relations.

Flags

Flag	Type	Default	Description
<archive.indx> (positional)	path	— (required)	The .indx archive to inspect.
--json	flag	off	Emit the full space.stats object as JSON instead of the human-readable summary.
--documents [type]	str (optional)	—	List documents, optionally filtered by detected type.

The --json output mirrors the SpaceStats model: documents, chunks, relations, embeddings, embed_dim, the per-type types histogram, and bytes_source. See data models for field meanings.

Output

By default inspect prints the space stats, a document-type histogram, and a sample of relations:

handbook.indx  (indx 1.0, produced by indx 0.4.2)
  documents 128   chunks 1042   relations 380   embed_dim 1536
  types   policy 41   guide 33   reference 29   faq 25
  relations (sample)
    chunk:0a1f → chunk:9c3e   follows
    chunk:7b22 → chunk:1d80   references
    doc:contracts → doc:terms  cross-references

With --documents [type], each row lists the document id, detected type, source path, and chunk count. Passing a type filters the listing to that detected type.

SDK equivalent: inspect reads the KnowledgeSpace you get from KnowledgeSpace.load("./ai-ready/handbook.indx"). It uses space.stats for the summary and space.documents(type=...) for the document listing.

indx query <archive.indx> "<text>"

Run a semantic search against a sealed archive and return the most similar chunks. The query text is embedded with the same embedder pinned in the archive manifest, guaranteeing query-time compatibility.

Flags

Flag	Type	Default	Description
<archive.indx> (positional)	path	— (required)	The .indx archive to search.
"<text>" (positional)	str	— (required)	The query string.
-k	int	5	Number of hits to return.
--type	str	—	Restrict results to a single document type.
--json	flag	off	Emit the results as a SearchHit[] JSON array (including .chunk, .neighbors, and .source).

Output

Default output is human-readable: for each hit, the rank, similarity score, source path, and chunk text along with its neighbor chunk ids (the context window). With --json, each element is a serialized SearchHit carrying the matched chunk, its score, and resolved neighbor chunks.

indx query ./ai-ready/handbook.indx "how long is data retained?" -k 3 --type policy

SDK equivalent:

from indx import KnowledgeSpace

space = KnowledgeSpace.load("./ai-ready/handbook.indx")
for hit in space.search("how long is data retained?", k=3):
    print(hit.score, hit.source.path)
    print(hit.chunk.text)

-k maps to the k argument of space.search(query, k=...). See the SDK reference.

indx app

Launch a local web UI that exercises the whole pipeline from the browser — configure a stack, run a build with live stage progress, then inspect and query the result. The server runs on one origin (it serves both the UI and a JSON + SSE /api) and operates on server-side paths. This command ships in the optional indx[app] extra (pip install "indx[app]").

Flags

Flag	Type	Default	Description
--host	str	127.0.0.1	Interface to bind.
--port	int	8000	Port to serve on.
--open / --no-open	flag	--open	Open (or don’t open) a browser on start.
--config, -c	path	./indx.toml if present	Configuration file to load into the editor.

indx app                       # http://127.0.0.1:8000, opens a browser
indx app --no-open --port 9000 # bind a different port, don't open a browser

If the indx[app] extra is not installed, indx app fails loud with a pip install "indx[app]" hint and exits 1 — a MissingDependencyError is a plain IndxError, so it maps to the fatal runtime code, not the configuration code (3). A missing UI bundle is non-fatal: the server still starts and serves /api, with a warning. Because app is a subcommand, a directory literally named app must be built as ./app (indx ./app --out ...).

See the web app guide for the four tabs, the Offline preset, and the dev workflow.

indx mcp <archive>

Serve a built knowledge space over the Model Context Protocol — the universal AI-agent connector. The server exposes three tools (indx_search, indx_overview, indx_get_document) to any MCP client: Claude Desktop, Cursor, or the TypeScript Mastra framework, with no Python on the client side. Ships in the optional indx[mcp] extra (or indx[agent]).

Flags

Flag	Type	Default	Description
<archive> (positional)	path	— (required)	A .indx archive or an output directory containing one.
--name	str	archive stem	Server name advertised to MCP clients.
--transport	str	stdio	MCP transport: stdio, sse, or streamable-http.

indx mcp ai-ready/handbook.indx                 # serve over stdio (Claude Desktop / Cursor)
indx mcp ai-ready/handbook.indx --transport sse # serve over SSE for a networked client

Like app, mcp is a subcommand, so a directory literally named mcp must be indexed as ./mcp (indx ./mcp --out ...). If the indx[mcp] extra is absent, the command fails with a pip install indx[mcp] hint and exits 1. For the Python equivalent (and in-process tools for LangChain, OpenAI Agents, Pydantic AI, and the Claude Agent SDK), see the AI agents guide and the SDK reference.

Exit codes

Every command returns one of these process exit codes:

Code	Meaning
0	Success.
1	Fatal pipeline/runtime error (including a --strict skip promoted to fatal).
2	Usage error (bad flags or arguments).
3	Configuration error (invalid indx.toml or an unknown component name).
4	Archive error (corrupt or incompatible .indx).

A nonexistent archive path is a usage error (2), not an archive error — inspect/query validate the path before the command runs. Exit 4 is reserved for a path that exists but is not a valid .indx (corrupt, not a zip, or an incompatible indx_version).

Strict mode changes the exit code

Without --strict, a single file that fails to parse or enrich is recorded as a per-item skip and the build still exits 0. With --strict, that same skip becomes fatal and the process exits 1. The full set of error categories and exit codes is covered in errors and exit codes.

See also

• Configuration reference — every indx.toml key and the precedence rules CLI flags participate in.
• SDK reference — the programmatic counterpart of every command above.
• Inspect and query guide — task-oriented walkthrough of the read-side commands.
• The web app (indx app) — the browser UI for the same configure → build → inspect → query workflow.
• Output formats — what --format produces.