index

Build or refresh the local search index for a repository.

Usage

unch index [flags]

Default state

unch index --root . builds or refreshes ./.semsearch.

Custom state dir

Use --state-dir when you want the index somewhere other than <root>/.semsearch.

Provider-aware snapshots

Each provider and model pair keeps its own active snapshot.

Common flow

1. Pick a repository root

   unch index --root .
   
2. Optionally pick a model or external state dir

   unch index --model qwen3 --state-dir /tmp/project.semsearch
   
3. Or use OpenRouter embeddings

   unch auth openrouter --token sk-or-...
   unch index --provider openrouter --model openai/text-embedding-3-small
   
4. Reuse warm state when possible

   Unchanged files reuse the existing file-hash cache and indexed snapshot data instead of rebuilding everything from scratch.

Flags

--root

Root directory to index. Defaults to ..

--state-dir

Path to a custom .semsearch directory. Defaults to <root>/.semsearch.

--db

Deprecated alias for the index location. Accepts .semsearch/index.db or a .semsearch directory, but --state-dir is the preferred interface.

--model

Embedding model to use. Accepts:

• embeddinggemma
• qwen3
• a direct path to a .gguf file
• an OpenRouter model id when --provider openrouter is selected

--provider

Embedding provider to use. Accepted values:

• llama.cpp
• openrouter

--exclude

Exclude glob pattern. Repeat it to add more patterns.

--lib

Path to a yzma library directory, or one of its shared library files.

--gitignore

Path to a .gitignore file. Defaults to <root>/.gitignore.

--ctx-size

llama context size. 0 uses the selected model default.

--verbose

Enable verbose yzma logging.

--comment-prefix

Legacy fallback comment prefix for unsupported files or parser failures.

--context-prefix

Legacy fallback file-context prefix for unsupported files or parser failures.

Examples

unch index --root .
unch index --exclude node_modules --exclude dist
unch index --model qwen3
unch auth openrouter --token sk-or-...
unch index --provider openrouter --model openai/text-embedding-3-small
unch index --model ~/.semsearch/models/Qwen3-Embedding-0.6B-Q8_0.gguf
unch index --state-dir /tmp/project.semsearch

Default repo-local state

unch index --root .

Custom state directory

unch index --root . --state-dir /tmp/project.semsearch

Different model

unch index --root . --model qwen3

OpenRouter

unch auth openrouter --token sk-or-...
unch index --root . --provider openrouter --model openai/text-embedding-3-small

Notes

• The first run may download the default embedding model and local yzma runtime libraries.
• OpenRouter token lookup checks OPENROUTER_API_KEY, then ~/.config/unch/tokens.json, then .semsearch/tokens.json.
• If the repository is currently bound to remote CI, a local reindex detaches that binding and returns the manifest to local mode.
• Use the same provider and model family for index and search, otherwise ranking quality will be wrong.

Why is --db deprecated?

unch state is no longer just one database file.

The full .semsearch directory contains index.db, manifest.json, filehashes.db, and related runtime state, so --state-dir is the more honest interface.

When do legacy prefix flags matter?

--comment-prefix and --context-prefix only matter in fallback indexing paths for unsupported files or parser failures.

They are not part of the normal Tree-sitter-based flow for supported languages.

What happens to remote binding after a local reindex?

A local reindex switches the manifest back to local-only mode.

Rebind with unch bind ci ... afterwards if you want that checkout to follow remote updates again.