Skip to main content

​
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

FlagLong FormDescription
-q--quietSuppress non-essential output
-v--verboseEnable verbose output
-f--forceSkip confirmation prompts
-p--profile <name>Target a specific profile
-g--globalOperate on global config

​
Commands

CommandDescription
ocx initInitialize OCX configuration
ocx addAdd components from a registry
ocx removeRemove installed components
ocx updateUpdate installed components
ocx searchSearch for components
ocx verifyVerify component integrity
ocx registryManage registries
ocx buildBuild a registry from source
ocx validateValidate a registry source without building
ocx selfUpdate or uninstall OCX itself
ocx profileManage global profiles
ocx configView and edit configuration
ocx opencodeLaunch OpenCode with resolved configuration

​
Global Options

These options are available on all commands:
OptionDescription
--cwd <path>Set working directory
--jsonOutput as JSON for scripting
-q, --quietSuppress non-essential output
-v, --verboseShow detailed output
-h, --helpShow help for command
-V, --versionShow version number

​
Exit Codes

CodeNameDescription
0SuccessCommand completed successfully
1GeneralUnspecified error
6ConflictResource already exists
66Not FoundResource not found
69NetworkNetwork/connectivity error
73IntegrityComponent hash mismatch
78ConfigConfiguration error

​
Environment Variables

VariableDescription
OCX_PROFILESet the active global profile for commands
OPENCODE_BINPath to custom OpenCode binary
OCX_NO_COLORDisable colored output
NO_COLORStandard no-color flag
OCX_SELF_UPDATESet to off to disable self-update functionality
OCX_NO_UPDATE_CHECKSet to 1 to disable update notifications on startup
EDITORText editor for ocx config edit
VISUALFallback 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"
    }
  }
}
Receipts are advisory records of what was installed. They help track provenance but do not enforce strict lockfile semantics.

​
See Also