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.
Overview
OCX provides a command-line interface for managing OpenCode profiles, component registries, and configuration. This page covers the full command set, global options, and conventions.
Short-Flag Policy
OCX follows a minimal short-flag policy inspired by Cargo and CLI Guidelines:
- Short flags (
-x) are reserved for high-frequency, cross-command options.
- Specialized options use long flags only (
--option-name).
Standard Short Flags
| Flag | Long Form | Description |
|---|
-q | --quiet | Suppress non-essential output |
-v | --verbose | Enable verbose output |
-f | --force | Skip confirmation prompts |
-p | --profile <name> | Target a specific profile |
-g | --global | Operate on global config |
Commands
| Command | Description |
|---|
ocx init | Initialize OCX configuration |
ocx add | Add components from a registry |
ocx remove | Remove installed components |
ocx update | Update installed components |
ocx search | Search for components |
ocx verify | Verify component integrity |
ocx registry | Manage registries |
ocx build | Build a registry from source |
ocx validate | Validate a registry source without building |
ocx self | Update or uninstall OCX itself |
ocx profile | Manage global profiles |
ocx config | View and edit configuration |
ocx opencode | Launch OpenCode with resolved configuration |
Global Options
These options are available on all commands:
| Option | Description |
|---|
--cwd <path> | Set working directory |
--json | Output as JSON for scripting |
-q, --quiet | Suppress non-essential output |
-v, --verbose | Show detailed output |
-h, --help | Show help for command |
-V, --version | Show version number |
Exit Codes
| Code | Name | Description |
|---|
| 0 | Success | Command completed successfully |
| 1 | General | Unspecified error |
| 6 | Conflict | Resource already exists |
| 66 | Not Found | Resource not found |
| 69 | Network | Network/connectivity error |
| 73 | Integrity | Component hash mismatch |
| 78 | Config | Configuration error |
Environment Variables
| Variable | Description |
|---|
OCX_PROFILE | Set the active global profile for commands |
OPENCODE_BIN | Path to custom OpenCode binary |
OCX_NO_COLOR | Disable colored output |
NO_COLOR | Standard no-color flag |
OCX_SELF_UPDATE | Set to off to disable self-update functionality |
OCX_NO_UPDATE_CHECK | Set to 1 to disable update notifications on startup |
EDITOR | Text editor for ocx config edit |
VISUAL | Fallback editor if EDITOR not set |
Configuration Files
Local Configuration
.opencode/ocx.jsonc
Local project configuration created by ocx init:
{
"$schema": "https://ocx.kdco.dev/schemas/ocx.json",
"registries": {
"kdco": {
"url": "https://ocx.kdco.dev"
}
},
"lockRegistries": false
}
Global Configuration
~/.config/opencode/ocx.jsonc
Global base configuration (used for downloading global settings like profiles, not applied to projects):
{
"registries": {
"kdco": {
"url": "https://ocx.kdco.dev"
}
}
}
Profile Configuration
~/.config/opencode/profiles/<name>/ocx.jsonc
Profile-specific OCX settings:
{
"registries": {
"kdco": {
"url": "https://ocx.kdco.dev"
}
},
"exclude": ["**/AGENTS.md", "**/CLAUDE.md", "**/CONTEXT.md"],
"include": [],
"bin": "/path/to/custom/opencode" // optional
}
Receipt File
.ocx/receipt.jsonc
Receipt tracking installed components (managed automatically):
{
"version": 1,
"installed": {
"kdco/researcher": {
"registry": "kdco",
"version": "1.2.0",
"hash": "abc123...",
"files": [".opencode/agents.md"],
"installedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:00:00Z"
}
}
}
See Also
