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

# CLI reference

> Commands, destination rules, output formats, and exit codes

Use `ocx --help` or `ocx <command> --help` for the installed version's options. This reference describes OCX 3 for OpenCode V2. `ocx oc --help` forwards to OpenCode's help.

## Commands

| Command | Purpose | Reference |
| - | - | - |
| `profile add/list/show/use/move/remove` | Create and manage named setups. | [Profiles](https://ocx.kdco.dev/docs/v2/cli/profiles.md) |
| `oc [native arguments...]` | Launch OpenCode using a selected profile. | [OpenCode launcher](https://ocx.kdco.dev/docs/v2/cli/opencode.md) |
| `init --global`, `init --project` | Initialize OCX metadata. | [Setup and configuration](https://ocx.kdco.dev/docs/v2/cli/configuration.md) |
| `config show/edit` | Inspect or edit OCX metadata at one scope. | [Setup and configuration](https://ocx.kdco.dev/docs/v2/cli/configuration.md) |
| `registry add/list/remove` | Manage registry sources. | [Sources and search](https://ocx.kdco.dev/docs/v2/cli/registries.md) |
| `search [query]`, `search --installed` | Browse sources or installed components. | [Sources and search](https://ocx.kdco.dev/docs/v2/cli/registries.md) |
| `add`, `update`, `remove`, `verify` | Manage owned files in a profile or project. | [Components](https://ocx.kdco.dev/docs/v2/cli/components.md) |
| `init --registry`, `validate`, `build` | Author a static file registry. | [Registry authoring commands](https://ocx.kdco.dev/docs/v2/cli/authoring.md) |
| `migrate` | Preview or apply an import into a new profile. | [Migration](https://ocx.kdco.dev/docs/v2/migration.md) |
| `self update/uninstall` | Manage the OCX installation. | [Self management](https://ocx.kdco.dev/docs/v2/cli/self.md) |

## Choose a destination

File operations always require exactly one destination:

```sh theme={null}
ocx add team/review --profile work
ocx add team/review --project
```

The first targets the named profile. The second targets `.opencode/` in the current directory, or the directory supplied by `--cwd`. Initialize a project with `ocx init --project` first.

`OCX_PROFILE` and `profile use` select launches; they never silently select a file-mutation destination. `--global` selects source metadata for browsing and profile creation, not a directory for installing components.

## Common options

Options are command-specific; the detailed pages list the supported set.

| Option | Meaning |
| - | - |
| `-p, --profile <name>` | Select a profile where supported. |
| `--project` | Select the current project's `.opencode/`. |
| `--cwd <path>` | Resolve project or authoring paths from another directory. |
| `--dry-run` | Prepare and report an operation without applying its changes. |
| `--json` | Write structured output for automation. |
| `-q, --quiet` | Suppress normal progress output where supported. |
| `-v, --verbose` | Include available diagnostic detail where supported. |

A dry-run can still fetch registry files and detect errors. It is a preview, not a reservation: rerunning an operation checks the then-current files and upstream content.

## JSON and automation

Successful JSON shapes depend on the command. For example, search returns `data.components`, profile listing returns `profiles` and `defaultProfile`, and verification returns `verified` and `errors`. Do not assume every success has the same envelope.

Handled failures with `--json` include `success: false`, an `error` with a code and message, and an `exitCode`. Argument-parser failures can still be ordinary CLI errors. Check the process exit code as well as the JSON content.

For dry-run reports, inspect `validation.passed` and any warnings; a preview may successfully describe an operation that would be refused. The [importer](https://ocx.kdco.dev/docs/v2/migration.md) likewise reports unresolved decisions without applying them.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Command completed; inspect preview warnings when applicable. |
| `1` | General or argument/operation validation failure. |
| `6` | Conflict, including modified/missing files found by `verify`. |
| `65` | Integrity mismatch, including an update blocked by edited or missing owned files. |
| `66` | Profile, component, or file not found. |
| `69` | Network or registry response failure. |
| `78` | Configuration, schema, or registry compatibility failure. |

`oc` returns the native child's exit status, including signal exits. Self-uninstall also distinguishes safety refusals and package-manager follow-up; see [its reference](https://ocx.kdco.dev/docs/v2/cli/self.md).


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