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

# remote

> Manage remote index publishing and sync via GitHub Actions.

Remote indexing is optional. Use it when you want GitHub Actions to build and publish an index so contributors can search without running `unch index` locally first.

The generated workflow file is `.github/workflows/unch-index.yml`.

<CardGroup cols={2}>
  <Card title="Create CI scaffold" icon="wand-magic-sparkles" href="#unch-create-ci">
    Generate the workflow file for remote indexing.
  </Card>

  <Card title="Bind local state" icon="link" href="#unch-bind-ci">
    Connect the current checkout to a repo or workflow URL.
  </Card>

  <Card title="Sync latest remote state" icon="arrows-rotate" href="#unch-remote-sync">
    Restore the newest published index into your local `.semsearch`.
  </Card>

  <Card title="Download by commit" icon="download" href="#unch-remote-download">
    Fetch a specific published artifact without rebinding to latest.
  </Card>
</CardGroup>

## Typical setup flow

1. Run `unch create ci`.
2. Run `unch bind ci <github-repo-or-workflow-url>`.
3. Commit and push the workflow.
4. After the workflow succeeds once, `unch search` and `unch remote sync` can restore the published state.

<Tabs>
  <Tab title="Bootstrap shared search">
    ```bash theme={null}
    unch create ci
    unch bind ci https://github.com/owner/repo
    git add .github/workflows/unch-index.yml
    git commit -m "ci: add unch remote indexing"
    git push
    ```
  </Tab>

  <Tab title="Pin to one commit">
    ```bash theme={null}
    unch remote download --commit abc123 https://github.com/owner/repo
    unch search --state-dir .semsearch "router middleware"
    ```
  </Tab>
</Tabs>

## `unch create ci`

Creates the remote index workflow scaffold.

```bash theme={null}
unch create ci
unch create ci --root ../other-repo
```

It writes `.github/workflows/unch-index.yml`.

## `unch bind ci`

Binds the local manifest to a GitHub repository URL or a direct workflow URL.

```bash theme={null}
unch bind ci https://github.com/uchebnick/unch
unch bind ci https://github.com/uchebnick/unch/actions/workflows/unch-index.yml
```

## `unch remote sync`

Refreshes local state from the bound remote workflow.

```bash theme={null}
unch remote sync
unch remote sync --root ../repo --allow-missing
```

Use `--allow-missing` in bootstrap flows where no published artifact exists yet, or when an incompatible older artifact should not fail the run.

## `unch remote download`

Downloads a published artifact for a specific commit without changing the repository binding.

```bash theme={null}
unch remote download --commit abc123 https://github.com/uchebnick/unch
unch remote download --commit abc123 https://github.com/uchebnick/unch/actions/workflows/unch-index.yml
```

The downloaded manifest is activated as local-only state so future searches do not auto-sync to the latest remote artifact by accident.

<Tip>
  Published remote state includes `index.db`, `manifest.json`, and `filehashes.db`, so warm reindex flows can reuse the file hash cache too.
</Tip>