CLI reference

The semanticastindexer (SAI) binary is a single CLI with an optional subcommand. With no subcommand it runs a full index of --root; subcommands cover storage maintenance (flush), incremental re-indexing (sync), similarity search (similar, duplicates), and the MCP server (mcp).

Run the binary from the target project’s repo root so stored payload paths stay project-relative (or point --root at the project’s source dir). Connection settings for the Qdrant backend are read from the environment, never hard-coded — see environment variables (QDRANT_URL, QDRANT_API_KEY). Persistent configuration lives in sai-cfg.yml; see the configuration reference for every key.

Synopsis

semanticastindexer [GLOBAL FLAGS] [INDEX FLAGS]            # default: full index of --root
semanticastindexer [GLOBAL FLAGS] init       [INIT FLAGS]
semanticastindexer [GLOBAL FLAGS] flush
semanticastindexer [GLOBAL FLAGS] sync       [SYNC FLAGS]
semanticastindexer [GLOBAL FLAGS] similar    [SIMILAR FLAGS]
semanticastindexer [GLOBAL FLAGS] duplicates [DUPLICATES FLAGS]
semanticastindexer [GLOBAL FLAGS] mcp        [MCP FLAGS]

Resolution order

Every value resolves in this order:

CLI flag > sai-cfg.yml config value > built-in default.

A CLI flag always overrides the config file, which always overrides the compiled-in default. This applies to the global flags, the index-only flags, and the per-subcommand similarity thresholds documented below.

Global flags (before or after the subcommand)

These flags are declared global = true, so they are accepted in any position — before or after the subcommand name.

Note: --backend, --embedder, --config, --collection, -v/--verbose, --log-format, --timing, and --silent are global. The index-only flags below (--root, --ext, --chunker, --model, --query, --query-only, --recreate, --dry-run, --limit) are not global — they belong to the default (no-subcommand) index action.

Default action — full index (no subcommand)

With no subcommand, SAI walks --root, chunks each matching file, embeds the chunks, and upserts them into the collection. The flags below are specific to this default action.

Examples:

BIN="$(pwd)/target/release/semanticastindexer"
cd /path/to/your/project

# See exactly what would be indexed/skipped — no network, no upload.
"$BIN" --root src --dry-run

# Index the TypeScript tree into a named collection.
"$BIN" --root src --ext ts,tsx --collection source_code

# Index Go later, into the same collection.
"$BIN" --root path/to/go --ext go --collection source_code

# Search only (read-only — does not upload the codebase).
"$BIN" --query-only --collection source_code \
    --query "where do we create the qdrant collection" --limit 10

# Drop & rebuild the collection before indexing.
"$BIN" --root src --ext ts,tsx --recreate

Two distinct --limit defaults

--limit exists in two places with different defaults — do not confuse them:

DuckDB dimension-mismatch prompt

On the indexing path (not --query-only), if opening the DuckDB backend fails because the existing index file was built with a different embedding model (a vector-dimension mismatch), SAI offers to delete the file and re-index from scratch. The prompt defaults to NO, and on a non-interactive stdin (CI, git hooks, the MCP stdio server) it auto-declines immediately and propagates the original error — it is never destructive in automation. Declining (or piping non-TTY input) leaves the index untouched. --query-only never re-indexes, so it surfaces the error without offering to delete anything.

init

Generate a starter sai-cfg.yml — the standard, fully-commented config. By default it runs a short interview (vector backend, embedder, collection, model, plus optional connection settings and extra excluded directories); every question has a default accepted by pressing Enter. The model’s vector_dim is filled in automatically for recognized models (Jina code, e5 family, mxbai-embed-large, nomic-embed-text) and asked for otherwise. The generated file is validated before it is written.

semanticastindexer init             # interactive interview
semanticastindexer init --yes       # accept every default (non-interactive)

On a closed/non-interactive stdin every question falls back to its default, so init is safe in scripts and CI even without --yes. init never loads an existing config, so it also works when the current one is broken.

flush

Delete the entire collection from the vector storage.

semanticastindexer flush

flush takes no subcommand-local flags (only the global flags apply). Useful for the one-time re-index when point-ID hashing changed, or to fully reset a collection.

sync

Re-index only changed files — intended for git hooks (post-commit, post-merge, pre-commit). For each changed file: delete its existing points, then upload the current content fresh. Files that were deleted or are now excluded are removed from the collection. sync honors the same --ext and sai-cfg.yml filters as a full index.

Examples:

# Diff HEAD~1..HEAD (e.g. post-commit / post-merge).
semanticastindexer sync --since HEAD~1

# Staged changes (e.g. pre-commit).
semanticastindexer sync --staged

# Explicit file list (overrides git).
semanticastindexer sync --file src/a.ts --file src/b.ts

If git detection (or the explicit list) yields no changed files, sync prints sync: no changed files and exits. Run hooks from the repo root so the paths git reports match the stored payload paths. See the keeping the index in sync guide for full hook examples.

similar

Print the nearest neighbours of either a code snippet or an existing indexed chunk, as score path:start-end symbol. Requires a vector backend feature (duckdb or qdrant).

Exactly-one-of validation

similar requires exactly one target:

• either --code
• or both --path and --line

Any other combination is a clear error:

Examples:

# Nearest neighbours of a snippet (embedded as a passage — code-vs-code).
semanticastindexer similar --code "function formatDuration(s) { return s }" --limit 8

# Nearest neighbours of an existing indexed chunk (stored vector, self-excluded).
semanticastindexer similar --path src/utils/transcriptParser.ts --line 103 --min-score 0.0

The similar --code path needs a local embedder (the DuckDB backend). Qdrant embeds server-side, so --code against --backend qdrant returns a clear error. similar --path/--line works on either backend (it reuses the stored vector, no re-embed).

duplicates

Codebase-wide near-duplicate clusters. For each chunk, takes its nearest neighbours, keeps edges with similarity >= min-score, and unions them into clusters (union-find). Prints clusters largest-first. Uses stored vectors only (no re-embed). Requires a vector backend feature (duckdb or qdrant).

Note the resolution asymmetry: --min-score, --min-cluster-size, and --top-k each resolve flag > config (similarity.*) > built-in default, while --max-clusters resolves flag > built-in default 50 with no config key.

Output format:

N near-duplicate cluster(s) (min_score 0.93, min_cluster_size 2, top_k 10):
cluster (size 3, sim 0.9412..0.9871):
  src/a.ts:10-40  formatDuration
  src/b.ts:5-35   formatTime
  ...

When no clusters meet the thresholds, SAI prints a single no near-duplicate clusters (...) line.

Examples:

# Config / built-in thresholds.
semanticastindexer duplicates

# Fully specified.
semanticastindexer duplicates --min-score 0.85 --top-k 10 \
    --min-cluster-size 2 --max-clusters 20 \
    --path-glob "src/utils/**"

Dirty-index prompt

Before scanning, duplicates checks whether the index contains dirty-stamped chunks (chunks recorded from an uncommitted working tree). If so:

• On an interactive TTY, it warns and asks to proceed; the prompt defaults to NO, and declining aborts the scan (the results may reflect uncommitted work).
• On a non-interactive stdin (CI, git hooks, MCP), it prints the warning to stderr and proceeds without prompting — it never blocks.
• With --silent, the dirty check is skipped entirely.

Like the dimension-mismatch prompt, this never triggers a destructive or blocking action in automation.

mcp

Run the MCP server (semantic code search for AI agents) over stdio. Requires the mcp feature. When --backend/--embedder are unset, the MCP server applies its own defaults of duckdb + ollama (the offline, no-quota path); explicit CLI flags and config values still take precedence via the normal merge. The shipped tool names are sai_-prefixed: sai_search_code, sai_find_similar, sai_find_duplicates, sai_index_status, sai_prepare_mcp_setup, and (gated) sai_refresh.

By default the MCP server is read-only: it never modifies the index or the filesystem. --allow-write gates the only write tool (sai_refresh); --allow-setup gates execution of sai_prepare_mcp_setup.

# Read-only MCP server (default duckdb + ollama).
semanticastindexer mcp

# Enable the sai_refresh write tool.
semanticastindexer mcp --allow-write

# Also allow sai_prepare_mcp_setup to run the setup script.
semanticastindexer mcp --allow-write --allow-setup

See the MCP server and tools reference for full tool details, and the glossary for terminology.

update

Self-update: download and install the latest GitHub release over the current binary by running the official release installer. Config-independent — works from any directory, needs no indexer.yaml, and is always compiled in (no feature gate).

semanticastindexer update

On macOS and Linux the installer replaces the binary in place; the new version takes effect on the next invocation (restart any running MCP servers to pick it up). On Windows a running executable cannot overwrite itself, so update prints the exact PowerShell one-liner to run instead.

Feature gating

SAI is built with Cargo features. Subcommands and chunkers are compiled in only when the matching feature is present:

The --features all build enables every backend, embedder, and chunker so any project can be indexed fully offline (ort + DuckDB) out of the box. Requesting --chunker ast (or auto-selecting it) without the ast feature fails early with a clear, actionable error before any work begins.

Logging

Diagnostics (status, progress, warnings, operation timing) are emitted to stderr at a configurable level and format. Stdout is reserved exclusively for JSON-RPC frames (MCP) and CLI data output (query hits, --json, sync report, --dry-run log).

Three knobs — level, format, and timing — each resolve in the same order: the RUST_LOG env var / CLI flag first, then the project config’s logging: block, then a built-in default.

Timing controls only the per-operation span-close durations (index/embed/query/sync). The single end-of-command summary line (done … in Ns) is a plain info event and prints regardless — see timing & output.

Examples:

# Default (info level, pretty format, no per-op timing).
semanticastindexer --dry-run

# Debug-level logs, JSON format.
RUST_LOG=semanticastindexer=debug semanticastindexer --log-format json --query "my query"

# Trace level (very verbose), with per-operation timing breakdowns.
semanticastindexer -vv --timing --query "my query"

# Suppress logs (error level only).
semanticastindexer --silent

Project-wide defaults can live in sai-cfg.yml instead of flags — see the logging: config block. The flags and RUST_LOG always override it.

For MCP clients: diagnostics go to stderr and are captured in the client’s log file. The JSON-RPC stream (stdout) remains clean, enabling write-mode (--allow-write) even with strict JSON-RPC clients (e.g. Grok). Because the server is launched with a fixed command, the logging: block is the simplest way to raise its verbosity without editing each client’s launch config.

Timing and output

Every top-level command is wrapped in a timing helper (run_timed). On completion it prints a single line to stderr:

done at <git-sha>[, dirty] in <seconds>s

((dry-run) is appended for a dry-run.) This timing/summary line — along with progress lines, dirty warnings, and the “no config” note — is suppressed by the global --silent flag, which is recommended for hooks and CI. Indexing progress (embedded N/M chunks, per-file lines) is also written to stderr; the actual results (indexed ..., query hits, similarity output) go to stdout.

See also

• Configuration reference — every sai-cfg.yml key.
• Environment variables — QDRANT_URL, QDRANT_API_KEY.
• Glossary — backend, embedder, chunker, and marker terms.