Skip to main content

​
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

unch index --root .

​
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.
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.
--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.
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.