> ## Documentation Index
> Fetch the complete documentation index at: https://unch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# index

> Build or refresh the local search index for a repository.

## Usage

```bash theme={null}
unch index [flags]
```

<CardGroup cols={3}>
  <Card title="Default state" icon="folder-tree">
    `unch index --root .` builds or refreshes `./.semsearch`.
  </Card>

  <Card title="Custom state dir" icon="folder-open">
    Use `--state-dir` when you want the index somewhere other than `<root>/.semsearch`.
  </Card>

  <Card title="Provider-aware snapshots" icon="brain">
    Each provider and model pair keeps its own active snapshot.
  </Card>
</CardGroup>

## Common flow

<Steps>
  <Step title="Pick a repository root">
    ```bash theme={null}
    unch index --root .
    ```
  </Step>

  <Step title="Optionally pick a model or external state dir">
    ```bash theme={null}
    unch index --model qwen3 --state-dir /tmp/project.semsearch
    ```
  </Step>

  <Step title="Or use OpenRouter embeddings">
    ```bash theme={null}
    unch auth openrouter --token sk-or-...
    unch index --provider openrouter --model openai/text-embedding-3-small
    ```
  </Step>

  <Step title="Reuse warm state when possible">
    Unchanged files reuse the existing file-hash cache and indexed snapshot data instead of rebuilding everything from scratch.
  </Step>
</Steps>

## 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

```bash theme={null}
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
```

<Tabs>
  <Tab title="Default repo-local state">
    ```bash theme={null}
    unch index --root .
    ```
  </Tab>

  <Tab title="Custom state directory">
    ```bash theme={null}
    unch index --root . --state-dir /tmp/project.semsearch
    ```
  </Tab>

  <Tab title="Different model">
    ```bash theme={null}
    unch index --root . --model qwen3
    ```
  </Tab>

  <Tab title="OpenRouter">
    ```bash theme={null}
    unch auth openrouter --token sk-or-...
    unch index --root . --provider openrouter --model openai/text-embedding-3-small
    ```
  </Tab>
</Tabs>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>