Usage
Description
Manage global profiles for different OpenCode configurations. Profiles give you portable, isolated configurations that work across repositories.Subcommands
ocx profile list— List all global profilesocx profile add— Create new profile or install from registryocx profile remove— Delete a profileocx profile move— Rename a profileocx profile show— Display profile contents
Profile List
List all available global profiles.Usage
Flags
| Flag | Shorthand | Default | Description |
|---|---|---|---|
--global | -g | true | List global profiles (required) |
--json | false | Output as JSON |
Examples
Output
Profile Add
Create a new profile, clone from existing, or install from a registry.Usage
Arguments
| Argument | Required | Description |
|---|---|---|
name | Yes | Profile name |
Flags
| Flag | Shorthand | Default | Description |
|---|---|---|---|
--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 | -g | true | Create global profile (required) |
Examples
Notes
- Profile names must be valid filesystem names.
- Spaces are automatically converted to hyphens.
--cloneaccepts: existing profile name.--sourceaccepts:registry/componentshorthand 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
Arguments
| Argument | Required | Description |
|---|---|---|
name | Yes | Profile name to delete |
Flags
| Flag | Shorthand | Default | Description |
|---|---|---|---|
--global | -g | true | Remove global profile (required) |
Examples
Notes
- Deletion is immediate (Cargo-style, no confirmation prompt).
- Cannot delete the last remaining profile.
Profile Move
Rename a profile.Usage
Arguments
| Argument | Required | Description |
|---|---|---|
old-name | Yes | Current profile name |
new-name | Yes | New profile name |
Flags
| Flag | Shorthand | Default | Description |
|---|---|---|---|
--global | -g | true | Move global profile (required) |
Examples
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_PROFILEenv var). - Self-rename (same old and new name) is a silent no-op.
Errors
| Error | Cause | Solution |
|---|---|---|
Profile "X" not found | Source profile not found | Check name with ocx profile list --global |
Cannot move: profile "Y" already exists | Target name conflicts | Remove existing profile first |
Profile Show
Display profile configuration and contents.Usage
Arguments
| Argument | Required | Description |
|---|---|---|
name | No | Profile name (defaults to resolved profile) |
Flags
| Flag | Shorthand | Default | Description |
|---|---|---|---|
--global | -g | true | Show global profile (required) |
--json | false | Output as JSON |
Examples
Output
See Also
- Profiles Overview — Core profile concepts and configuration.
- Profile Configuration — Detailed settings reference.
- Profile Security — Lock down recipes.
- ocx opencode — Launch OpenCode with a profile.