> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sources and search

> Configure scoped registry aliases and browse available or installed components

## Add a registry

```sh theme={null}
ocx registry add https://registry.example.com/opencode-v2 --name team --global
ocx registry add https://registry.example.com/opencode-v2 --name team --profile work
ocx registry add https://registry.example.com/opencode-v2 --name team --project --dry-run
```

Choose exactly one scope:

| Scope | Used by |
| - | - |
| `--global` | Unscoped `search` and `profile add --source`. |
| `--profile <name>` | Component commands and search for that profile. |
| `--project` | Component commands and search for that project's `.opencode/`. |

Aliases use lowercase letters/digits separated by single hyphens, up to 64 characters. The URL must use `https:`, `http:`, or `file:` and serve a protocol-3 registry. Adding a source fetches and validates its index, even during a dry-run.

The same alias and URL are an idempotent operation that preserves configured authentication headers. Reusing an alias with another URL, or registering one URL under another alias in the same scope, is a conflict. Remove the old entry before adding the replacement.

For a private registry that requires authentication even to read its index, add the URL and header placeholders through `config edit` first. Then test with `search`. See [authentication](https://ocx.kdco.dev/docs/v2/configuration.md#registry-authentication).

## List and remove sources

```sh theme={null}
ocx registry list --global
ocx registry ls --profile work --json
ocx registry remove team --project
# Alias: ocx registry rm team --project
```

Removing a source changes metadata, not installed files. Updates continue fetching from the origins recorded in the receipt, even if an alias is removed or configured with another URL. An explicit `add` from a different origin is refused for an already owned component; changing metadata does not transfer ownership to a new publisher.

Registry commands accept `--cwd <directory>`, `--json`, and `-q, --quiet` as well as their required scope. Only `registry add` supports `--dry-run`. Global/project metadata with `lockRegistries: true` refuses source mutations.

## Search available components

```sh theme={null}
ocx search
ocx search review --profile work
ocx search review --project --limit 50 --json
```

Without a scope, search reads global sources. `--profile` and `--project` select their own source sets; sources do not cascade between scopes. Search matches names and descriptions, and returns at most 20 results unless you set a positive `--limit`.

Search needs no OpenCode runtime. Registry errors are reported instead of silently presenting incomplete results.

## List installed components

```sh theme={null}
ocx search --installed --profile work
ocx list --installed --project --json
```

`list` is an alias for `search`. Installed mode reads the selected destination's receipt and requires an explicit profile or project. It lists all installed entries; the search query and result limit apply to catalog search, not this receipt listing. It does not refresh or verify files.

Search supports `--installed`, `-p, --profile`, `--project`, `--limit`, `--cwd`, `--json`, `-q, --quiet`, and `-v, --verbose`. JSON results use `data.components`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.