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

# search

> Query the local index with semantic, lexical, or mixed retrieval.

## Usage

```bash theme={null}
unch search [flags] <query>
```

The query can be passed positionally or with `--query`. When both are present, `--query` wins.

<CardGroup cols={3}>
  <Card title="Auto mode" icon="sparkles">
    Best default for natural-language queries about behavior.
  </Card>

  <Card title="Semantic mode" icon="brain">
    Force embedding-only retrieval when you want conceptual matches.
  </Card>

  <Card title="Lexical mode" icon="binary">
    Force exact-term retrieval when you already know the identifier or string.
  </Card>
</CardGroup>

## Common search patterns

<Tabs>
  <Tab title="Behavior query">
    ```bash theme={null}
    unch search "create a new router"
    ```
  </Tab>

  <Tab title="Exact symbol">
    ```bash theme={null}
    unch search --mode lexical "ParseQuery"
    ```
  </Tab>

  <Tab title="Detailed inspection">
    ```bash theme={null}
    unch search --details "get path variables from a request"
    ```
  </Tab>

  <Tab title="External state dir">
    ```bash theme={null}
    unch search --state-dir /tmp/project.semsearch "router middleware"
    ```
  </Tab>
</Tabs>

## Flags

### `--query`

Explicit search query text.

### `--mode`

Accepted values:

* `auto`
* `semantic`
* `lexical`

### `--limit`

Maximum number of results to return.

### `--max-distance`

Maximum semantic distance kept in `auto` and `semantic` modes. Set `0` or a negative value to disable filtering.

### `--details`

Show symbol kind, name, signature, docs, and body context for each result.

### `--model`

Query embedding model. Must match the model used when the index was built.

### `--provider`

Embedding provider. Must match the provider used when the index was built.

### `--root`

Root directory used to render result paths relative to the repository.

### `--state-dir`

Path to a custom `.semsearch` directory. This is the preferred way to search external state.

### `--db`

Deprecated alias for the index location. Prefer `--state-dir`.

### `--lib`

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

### `--ctx-size`

llama context size. `0` uses the selected model default.

### `--verbose`

Enable verbose `yzma` logging.

## Examples

```bash theme={null}
unch search "sqlite schema"
unch search --mode lexical "Run"
unch search --details "get path variables from a request"
unch search --model qwen3 "search query"
unch search --provider openrouter --model openai/text-embedding-3-small "search query"
unch search --state-dir /tmp/project.semsearch "router middleware"
```

## Notes

* `auto` stays semantic-first for natural-language queries.
* If the manifest is bound to remote CI, `unch search` can refresh from remote automatically before running the query.
* OpenRouter token lookup checks `OPENROUTER_API_KEY`, then `~/.config/unch/tokens.json`, then `.semsearch/tokens.json`.
* If no active snapshot exists for the requested provider and model, `unch` tells you to run `unch index --provider <provider> --model <model>` first.

<AccordionGroup>
  <Accordion title="When should I force lexical mode?">
    Force lexical mode when you already know the identifier, string literal, or exact term you want to match.
  </Accordion>

  <Accordion title="When should I force semantic mode?">
    Force semantic mode when the query is about behavior or intent and exact string overlap is weak.
  </Accordion>

  <Accordion title="Why should index and search use the same model?">
    Ranking quality depends on query and document embeddings living in the same provider and model space.

    If you indexed with one provider or model and search with another, the results may degrade or fail entirely.
  </Accordion>
</AccordionGroup>