Skip to main content

Usage

ocx profile <subcommand> [options]
ocx p <subcommand> [options]  # alias

Description

Manage global profiles for different OpenCode configurations. Profiles give you portable, isolated configurations that work across repositories.

Subcommands


Profile List

List all available global profiles.

Usage

ocx profile list --global [options]
ocx p ls --global [options]  # alias

Flags

FlagShorthandDefaultDescription
--global-gtrueList global profiles (required)
--jsonfalseOutput as JSON

Examples

# List all profiles
ocx profile list --global

# List with JSON output
ocx p ls --global --json

Output

$ ocx profile list --global
Global profiles:
  default
  work
  client-x

$ ocx profile list --global --json
{
  "profiles": ["default", "work", "client-x"],
  "initialized": true
}

Profile Add

Create a new profile, clone from existing, or install from a registry.

Usage

ocx profile add <name> [options]
ocx p add <name> [options]  # alias

Arguments

ArgumentRequiredDescription
nameYesProfile name

Flags

FlagShorthandDefaultDescription
--clone <profile>Clone from existing profile
--source <name/component>Install profile from registry component
--from <url>Ephemeral registry URL for profile installation (used with --source)
--global-gtrueCreate global profile (required)

Examples

# Create new empty profile
ocx profile add work --global

# Clone from existing profile
ocx profile add client-x --clone work --global

# Install from registry with ephemeral URL (not saved)
ocx profile add ws --source kit/ws --from https://ocx-kit.kdco.dev --global

# First add global registry, then install profile
ocx registry add https://ocx-kit.kdco.dev --name kit --global
ocx profile add ws --source kit/ws --global

# Overwrite existing profile (remove and re-add)
ocx profile remove ws --global
ocx profile add ws --source kit/ws --global

Notes

  • Profile names must be valid filesystem names.
  • Spaces are automatically converted to hyphens.
  • --clone accepts: existing profile name.
  • --source accepts: registry/component shorthand for profile components.
  • --from (with --source) provides ephemeral registry URL without saving to config.
  • To overwrite an existing profile, remove it first with ocx profile rm <name> --global, then add again.

Profile Remove

Delete a profile.

Usage

ocx profile remove <name> [options]
ocx p rm <name> [options]  # alias

Arguments

ArgumentRequiredDescription
nameYesProfile name to delete

Flags

FlagShorthandDefaultDescription
--global-gtrueRemove global profile (required)

Examples

# Remove a profile
ocx profile remove old-profile --global

Notes

  • Deletion is immediate (Cargo-style, no confirmation prompt).
  • Cannot delete the last remaining profile.

Profile Move

Rename a profile.

Usage

ocx profile move <old-name> <new-name> [options]
ocx p mv <old-name> <new-name> [options]  # alias

Arguments

ArgumentRequiredDescription
old-nameYesCurrent profile name
new-nameYesNew profile name

Flags

FlagShorthandDefaultDescription
--global-gtrueMove global profile (required)

Examples

# Rename a profile
ocx profile move work client-work --global

Notes

  • Profile names must be 1–32 characters, alphanumeric with dots, underscores, hyphens.
  • Cannot rename to a name that already exists (remove target first).
  • Warns if renaming the active profile (update OCX_PROFILE env var).
  • Self-rename (same old and new name) is a silent no-op.

Errors

ErrorCauseSolution
Profile "X" not foundSource profile not foundCheck name with ocx profile list --global
Cannot move: profile "Y" already existsTarget name conflictsRemove existing profile first

Profile Show

Display profile configuration and contents.

Usage

ocx profile show [name] --global [options]
ocx p show [name] --global [options]  # alias

Arguments

ArgumentRequiredDescription
nameNoProfile name (defaults to resolved profile)

Flags

FlagShorthandDefaultDescription
--global-gtrueShow global profile (required)
--jsonfalseOutput as JSON

Examples

# Show current profile (uses resolved profile)
ocx profile show --global

# Show work profile config
ocx profile show work --global

# Get JSON output
ocx p show work --global --json

Output

$ ocx profile show work --global
Profile: work
Path: /Users/username/.config/opencode/profiles/work/

Files:
  ocx.jsonc
  opencode.jsonc
  AGENTS.md

Configuration:
  Registries: kdco
  Exclude patterns: **/AGENTS.md, **/CLAUDE.md
  Include patterns: (none)

See Also