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

# Installation

> Install unch with npm, Homebrew, shell installer, PowerShell, go install, or build from source.

<CardGroup cols={3}>
  <Card title="Fastest path" icon="bolt">
    Use npm for the simplest cross-platform install.
  </Card>

  <Card title="Native installers" icon="box-archive">
    Homebrew, shell installer, and PowerShell installer are available when you prefer platform-native flows.
  </Card>

  <Card title="Most flexible" icon="sliders">
    Use `go install` or build from source when you want a local checkout or custom toolchain flow.
  </Card>
</CardGroup>

## Requirements

The npm package and release installers use published archives by default, so Go is not required on supported targets.

If you install with `go install`, build from source, or install on a target without a matching release archive, you need:

* Go 1.25+
* a working C toolchain

On Windows source builds, that means an MSYS2 or MinGW-style toolchain, or an equivalent setup.

## Choose an install path

<Tabs>
  <Tab title="npm (recommended)">
    ```bash theme={null}
    npm install -g @uchebnick/unch
    ```

    This installs the `unch` CLI and downloads the matching native release binary for your platform.

    Verify it:

    ```bash theme={null}
    unch --version
    unch --help
    ```

    To use unch inside Codex as MCP tools plus the `unch` skill:

    ```bash theme={null}
    unch codex install
    ```

    Then restart Codex. The setup command uses `codex mcp add` for the MCP server and writes the skill to `~/.codex/skills/unch/SKILL.md`.

    If you prefer not to add Codex integration, you can skip `unch codex install`.
  </Tab>

  <Tab title="Homebrew (macOS)">
    ```bash theme={null}
    brew install uchebnick/tap/unch
    ```

    Upgrade later with:

    ```bash theme={null}
    brew upgrade unch
    ```
  </Tab>

  <Tab title="Shell installer (macOS/Linux)">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /usr/local/bin
    ```

    This installs `unch` into a system `PATH` directory so you can run it immediately after the installer finishes.

    On Apple Silicon macOS, use `/opt/homebrew/bin` instead of `/usr/local/bin`:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /opt/homebrew/bin
    ```

    Pin a version or choose a destination:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /usr/local/bin
    curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /usr/local/bin -v <tag>
    ```

    `install.sh` verifies downloaded release archives against the published `checksums.txt` file. It is smoke-tested in CI on Ubuntu, Debian, Arch, and NixOS-like Linux environments, including the default no-`-b` path selection flow.
  </Tab>

  <Tab title="PowerShell (Windows)">
    ```powershell theme={null}
    iwr https://raw.githubusercontent.com/uchebnick/unch/main/install/install.ps1 -useb | iex
    ```

    Default install location:

    ```text theme={null}
    $HOME\AppData\Local\Programs\unch\bin
    ```

    After downloading the script locally, you can override the target or pin a version:

    ```powershell theme={null}
    .\install\install.ps1 -BinDir "C:\Tools\unch\bin" -Version <tag>
    ```

    `unch` is available immediately in the current PowerShell session after the installer finishes.
    To keep it available in future PowerShell or terminal sessions, add `$HOME\AppData\Local\Programs\unch\bin` to your user `PATH`.

    The PowerShell installer is smoke-tested in CI on Windows `x86_64` and `arm64`.
  </Tab>

  <Tab title="go install">
    ```bash theme={null}
    go install github.com/uchebnick/unch/cmd/unch@latest
    ```

    This install path requires a cgo-capable Go toolchain. It is smoke-tested in CI in the official Debian-based Go container image. To pin a specific release, use `@<tag>`.

    Older references to `github.com/uchebnick/unch-searcher` should be treated as legacy.
  </Tab>

  <Tab title="Build from source">
    ```bash theme={null}
    git clone https://github.com/uchebnick/unch.git
    cd unch
    go build -o unch ./cmd/unch
    ```

    On Windows:

    ```powershell theme={null}
    go build -o unch.exe ./cmd/unch
    ```
  </Tab>
</Tabs>

## Published release archives

| Platform | Architectures     | Status    |
| -------- | ----------------- | --------- |
| macOS    | `arm64`, `x86_64` | Supported |
| Linux    | `arm64`, `x86_64` | Supported |
| Windows  | `arm64`, `x86_64` | Supported |

## Verify the install

```bash theme={null}
unch --version
unch --help
```

If you installed through npm and want Codex integration:

```bash theme={null}
unch codex install
```

## Configure OpenRouter

If you want to use OpenRouter for embeddings instead of the local `llama.cpp` runtime:

```bash theme={null}
unch auth openrouter --token sk-or-...
unch index --provider openrouter --model openai/text-embedding-3-small
```

By default `unch auth openrouter` stores the token in:

```text theme={null}
~/.config/unch/tokens.json
```

That keeps the token out of your project checkout and out of your shell environment.

For one repository only, use:

```bash theme={null}
unch auth openrouter --token sk-or-... --local
```

That writes:

```text theme={null}
.semsearch/tokens.json
```

<AccordionGroup>
  <Accordion title="When should I prefer release installers?">
    Prefer the release installers when your platform has a matching published archive and you just want a working binary quickly.

    That path does not require Go and is the one covered by install smoke checks in CI.
  </Accordion>

  <Accordion title="When should I use go install or build from source?">
    Use source-based install when you want to work from a checkout, pin your own toolchain, or run on a target without a matching release archive.
  </Accordion>

  <Accordion title="What is special about Windows source builds?">
    Windows source builds need a working C toolchain.

    In practice that means MSYS2, MinGW, or an equivalent environment that can build the Tree-sitter and SQLite dependencies.
  </Accordion>
</AccordionGroup>

<Tip>
  If `unch` is installed but not found, make sure the installer destination is on your `PATH`.
</Tip>