Command Line

General Options

The following options are available for all commands and must be specified before the command name.

--log-level

The log level for OCX, which can be set to one of the following values:

• off: No logs will be emitted.
• error: Only error messages will be emitted.
• warn: Warning messages and error messages will be emitted. This is the default log level.
• info: Informational messages, warning messages, and error messages will be emitted.
• debug: Debug messages, informational messages, warning messages, and error messages will be emitted.
• trace: All messages will be emitted, including trace messages.

--format

When set, ocx will output information in the specified format instead of plain text. Supported formats are:

• plain (default): Human-readable plain text.
• json: Machine-readable JSON format.

The available data depends on the command being executed.

--offline

When set, ocx will run in offline mode, which will not attempt to fetch any remote information. If any command requires information that is not already available locally, it will fail with an error.

--remote

When set, ocx will use the remote index by default instead of the local index. Combining this flag with --offline will most likely result in an error.

--index

Override the path to the local index directory for this invocation. By default, ocx reads the local index from $OCX_HOME/index/ (typically ~/.ocx/index/).

ocx --index /path/to/bundled/index install cmake:3.28

This flag is intended for environments where the local index is bundled alongside a tool rather than living inside OCX_HOME — for example inside a GitHub Action, Bazel Rule, or DevContainer Feature that ships a frozen index snapshot as part of its release.

The flag has no effect when --remote is set.

The same override can be set persistently via the OCX_INDEX environment variable. The --index flag takes precedence when both are set.

--color

Controls when to use ANSI colors in output.

• auto (default): Enable colors when stdout is a terminal and NO_COLOR is not set.
• always: Always emit color codes, even when piped.
• never: Disable all color output.

The --color flag takes the highest precedence over all color-related environment variables (NO_COLOR, CLICOLOR, CLICOLOR_FORCE).

--config

Path to an ocx configuration file.

ocx --config /path/to/config.toml install cmake:3.28

--candidate / --current

The --candidate and --current flags are available on commands that resolve a package's content path, for example env, find, or shell env.

By default these commands use the content-addressed path in the object store — a hash-derived directory that changes whenever the package is reinstalled at a different version. Use --candidate or --current to resolve via a stable install symlink instead, whose path never changes regardless of the underlying object. This is useful for paths embedded in editor configs, Makefiles, or shell profiles that should survive package updates.

Mode	Flag	Path
Object store (default)	(none)	~/.ocx/objects/…/{digest}/content
Candidate symlink	--candidate	~/.ocx/symlinks/…/candidates/{tag}/content
Current symlink	--current	~/.ocx/symlinks/…/current/content

Constraints

• --candidate: the package must already be installed. Digest identifiers are rejected — use a tag identifier.
• --current: a version must be selected first (via select or install --select). Digest identifiers are rejected. The tag portion of the identifier is ignored — only registry and repository are used to locate the symlink.
• --candidate and --current are mutually exclusive.

Commands

clean

Removes unreferenced objects from the local object store.

An object is unreferenced when nothing points to it — no candidate or current symlink, and no other installed package depends on it. This happens after uninstall (without --purge) or when symlinks are removed manually. When a package with dependencies is removed, its dependencies may become unreferenced and are cleaned up in the same pass.

DANGER

Do not run clean concurrently with other OCX commands. A concurrent install may reference an object that clean is about to remove, causing the install to fail.

Usage

ocx clean [OPTIONS]

Options

• --dry-run: Show what would be removed without making any changes.
• -h, --help: Print help information.

deps

Shows the dependency tree for one or more installed packages. Operates on locally-present packages only — no auto-install. See Dependencies in the user guide for background.

Usage

ocx deps [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to inspect. Accepts multiple packages — when given more than one, the command builds the combined dependency graph (the same graph exec uses for environment composition).

Options

• --flat: Show the resolved evaluation order instead of the tree. This is the exact order exec and env use for environment composition — useful for debugging unexpected variable values.
• --why <DEP>: Explain why a dependency is pulled in. Shows all paths from the given root packages to <DEP>. Mutually exclusive with --flat.
• --depth <N>: Limit tree depth. --depth 1 shows direct dependencies only.
• -p, --platform: Target platforms to consider when resolving packages.
• -h, --help: Print help information.

Default output is a logical tree showing declared dependencies. Diamond dependencies (the same package reached via multiple paths) are marked with (*) and their subtree is not expanded again:

myapp:1.0 (sha256:aaa1b2c3…)
├── ocx.sh/java:21 (sha256:bbb4e5f6…)
└── ocx.sh/cmake:3.28 (sha256:ccc7d8e9…)
    └── ocx.sh/gcc:13 (sha256:ddd0a1b2…)

--flat shows the combined evaluation order after topological sort and deduplication:

Package            Digest
ocx.sh/gcc:13      sha256:ddd0a1b2…
ocx.sh/cmake:3.28  sha256:ccc7d8e9…
ocx.sh/java:21     sha256:bbb4e5f6…
myapp:1.0          sha256:aaa1b2c3…

--why traces all paths from roots to a specific dependency:

myapp:1.0 → ocx.sh/cmake:3.28 → ocx.sh/gcc:13

deselect

Removes the current-version symlink for one or more packages.

The package is deselected but not uninstalled: its candidate symlink and object-store content remain intact. To also remove the installed files, use uninstall.

Usage

ocx deselect <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to deselect.

Options

• -h, --help: Print help information.

env

Print the resolved environment variables for one or more packages.

Plain format outputs an aligned table with Key, Type and Value columns. JSON format outputs {"entries": [{"key": "…", "value": "…", "type": "constant"|"path"}, …]}.

If a package declares dependencies, their environment variables are included in the output in topological order — dependencies before dependents.

In the default mode, packages are auto-installed if not already available locally (including transitive dependencies). See Path Resolution for the --candidate and --current modes.

Usage

ocx env [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to resolve the environment for.

Options

• -p, --platform: Target platforms to consider when resolving packages.
• --candidate, --current: Path resolution mode — see Path Resolution.
• -h, --help: Print help information.

exec

Executes a command within the environment of one or more packages. Packages are auto-installed if not already available locally (unless --offline is set). If a package declares dependencies, their environment variables are applied in topological order before the package's own variables.

Usage

ocx exec [OPTIONS] <PACKAGE>... -- <COMMAND> [ARGS...]

Arguments

• <PACKAGE>: Package identifiers to run within.
• <COMMAND>: The command to execute within the package environment.
• [ARGS...]: Arguments to pass to the command.

Options

• -p, --platform: Specify the platforms to use.
• -i, --interactive: Run in interactive mode, forwarding stdin to the child process.
• --clean: Start with a clean environment containing only the package-defined variables, instead of inheriting the current shell environment.
• -h, --help: Print help information.

find

Resolves one or more packages and prints their content directory paths.

Resolves the content directory for each package. See Path Resolution for the difference between the default object-store path and the stable symlink modes.

No downloading is performed — the package must already be installed.

Usage

ocx find [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to resolve.

Options

• -p, --platform: Platforms to consider when resolving. Defaults to the current platform. Ignored when --candidate or --current is set.
• --candidate, --current: Path resolution mode — see Path Resolution.
• -h, --help: Print help information.

TIP

Use --format json with jq to embed the path in a script:

cmake_root=$(ocx find --candidate --format json cmake:3.28 | jq -r '.["cmake:3.28"]')

index

catalog

ocx index catalog [OPTIONS]

Lists all packages available in the index. Uses the local index by default; pass --remote to query the registry directly.

Options

• --with-tags: Include available tags for each package. Slower — requires fetching additional information for each package.

list

ocx index list [OPTIONS] <PACKAGE>...

Lists available tags for one or more packages.

Arguments

• <PACKAGE>: Package identifiers to list tags for.

Options

• --platforms: Shows which platforms are available for the package. Uses the tag from the identifier, or latest if none specified.
• --variants: Lists unique variant names found in the tags.
• -h, --help: Print help information.

update

ocx index update <PACKAGE>...

Updates the local index by fetching the latest information from the remote index for the specified packages.

When a tagged identifier is used (e.g., cmake:3.28), only that single tag's digest and manifest are fetched — the remote tag listing is skipped entirely. This is ideal for lockfile workflows where the local index should contain only explicitly requested tags. When a bare identifier is used (e.g., cmake), all tags are fetched as before.

Arguments

• <PACKAGE>: Package identifiers to update in the local index for. Include a tag to update only that tag; omit the tag to update all tags.

info

Prints build information: the ocx version, supported platforms, and the detected shell.

Usage

ocx info

install

Downloads and installs one or more packages into the local object store.

Installs packages into the object store and creates a candidate symlink for each package, making them available for use by other commands. If a package declares dependencies, all transitive dependencies are downloaded to the object store automatically — only the explicitly requested packages receive install symlinks.

Usage

ocx install [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to install.

Options

• -p, --platform: Target platforms to consider.
• -s, --select: After installing, update the current symlink for each package to point to the newly installed version. Required before using ocx env --current or ocx shell env --current.
• -h, --help: Print help information.

select

Selects one or more packages as the current version by updating the current symlink.

Each package is resolved using the selected index. No downloading is performed — the package must already be installed.

Usage

ocx select [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to select.

Options

• -p, --platform: Target platforms to consider when resolving packages.
• -h, --help: Print help information.

TIP

ocx install --select installs and selects in one step.

See path resolution modes for how the current symlink is used downstream.

shell

env

Generate shell export statements for the environment variables declared by one or more packages. Intended to be evaluated by the shell:

eval "$(ocx shell env mypackage)"

This command does not auto-install packages — if a package is not already available locally it will fail with an error. See Path Resolution for the --candidate and --current modes.

Usage

ocx shell env [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to generate environment variable export statements for.

Options

• -p, --platform: Target platforms to consider. Auto-detected by default.
• -s, --shell <SHELL>: Shell dialect to emit. Auto-detected by default.
• --candidate, --current: Path resolution mode — see Path Resolution.

completion

Generate shell completion scripts for ocx.

Usage

ocx shell completion [OPTIONS]

Options

• --shell <SHELL>: The shell to generate the completions for (e.g., bash, zsh, fish). By default, ocx will attempt to auto-detect the shell and generate the appropriate completions.

profile

Manage the shell profile — packages whose environment variables are loaded into every new shell session.

The profile is stored in $OCX_HOME/profile.json. The env file (sourced by your shell profile) calls ocx --offline shell profile load at startup to resolve all profiled packages and emit shell exports.

add

Add one or more packages to the shell profile.

Usage

ocx shell profile add [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to add to the profile.

Options

• --candidate: Resolve via the candidates/{tag} symlink (default, pinned). Requires a tag in the identifier.
• --current: Resolve via the current symlink (floating pointer set by ocx select).
• --content: Resolve via the content-addressed object store path. The path changes whenever the package is reinstalled at a different version.

Packages that are not yet installed will be auto-installed. For --current mode, install with --select first to create the current symlink (ocx install --select <pkg>).

remove

Remove one or more packages from the shell profile.

Usage

ocx shell profile remove <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to remove from the profile.

This does not uninstall the package — it only removes it from the profile manifest.

list

List all packages in the shell profile with their status.

Usage

ocx shell profile list

Shows each profiled package with its resolution mode (candidate, current, or content), status (active or broken), and resolved path.

load

Output shell export statements for all profiled packages.

Usage

ocx shell profile load [OPTIONS]

Options

• -s, --shell <SHELL>: Shell to generate exports for. Auto-detected if not specified.

Reads $OCX_HOME/profile.json and emits shell-specific export lines for each package's declared environment variables. Broken entries are silently skipped. This command is intended to be called from the env file via eval:

eval "$(ocx --offline shell profile load)"

uninstall

Removes the installed candidate for one or more packages.

Removes the candidate symlink and its back-reference. Object-store content is preserved unless --purge is given. To also remove the current symlink, pass --deselect or run deselect separately. To remove all unreferenced objects at once, use clean.

Usage

ocx uninstall [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to uninstall.

Options

• -d, --deselect: Also remove the current symlink. Equivalent to running ocx deselect after uninstall.
• --purge: Delete the object from the store when no other references remain after uninstall.
• -h, --help: Print help information.

version

Prints the ocx version number.

Usage

ocx version

ci

export

Exports the environment variables declared by one or more packages directly into a CI system's runtime files. For GitHub Actions, this appends path entries to $GITHUB_PATH and other variables to $GITHUB_ENV.

The CI flavor is auto-detected from the environment (e.g. GITHUB_ACTIONS=true) but can be overridden with --flavor.

This command does not auto-install packages — if a package is not already available locally it will fail with an error. In CI workflows, use package pull before ci export.

Usage

ocx ci export [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to export the environment for.

Options

• --flavor <FLAVOR>: CI system to target. Currently supported: github-actions. Auto-detected if omitted.
• -p, --platform: Target platforms to consider when resolving packages.
• --candidate, --current: Path resolution mode — see Path Resolution.
• -h, --help: Print help information.

TIP

Pair with package pull for a minimal CI setup:

ocx package pull cmake:3.28
ocx ci export cmake:3.28

package

create

Bundles a local directory into a compressed package archive ready for publishing. If the package metadata includes dependencies, the declared dependency graph is validated for cycles at this stage — catching errors before the package reaches the registry.

Usage

ocx package create [OPTIONS] <PATH>

Arguments

• <PATH>: Path to the directory to bundle.

Options

• -i, --identifier <IDENTIFIER>: Package identifier, used to infer the output filename when --output is a directory.
• -p, --platform <PLATFORM>: Platform of the package, used to infer the output filename.
• -o, --output <PATH>: Output file or directory. If a directory is given, the filename is inferred from the identifier and platform. The file extension controls the compression algorithm: .tar.xz (LZMA, default) or .tar.gz (Gzip).
• -f, --force: Overwrite the output file if it already exists.
• -m, --metadata <PATH>: Path to a metadata file to bundle with the package. When provided, it is copied as a sidecar file next to the output archive. If omitted, no metadata sidecar is written.
• -l, --compression-level <LEVEL>: Compression level (fast, default, best). Default: default. Applies to whichever algorithm is selected.
• -j, --threads <N>: Number of compression threads. 0 (default) auto-detects from available CPU cores (capped at 16). 1 forces single-threaded compression. Only affects LZMA (.tar.xz) compression.
• -h, --help: Print help information.

pull

Downloads packages into the local object store without creating install symlinks.

Unlike install, this command only populates the content-addressed object store — no candidate or current symlinks are created. If a package declares dependencies, all transitive dependencies are pulled into the object store as well. This is the recommended primitive for CI environments where reproducibility matters and symlink management is unnecessary.

Usage

ocx package pull [OPTIONS] <PACKAGE>...

Arguments

• <PACKAGE>: Package identifiers to pull.

Options

• -p, --platform: Target platforms to consider. Defaults to the current platform.
• -h, --help: Print help information.

TIP

package pull reports the content-addressed object store path for each package — the same digest-derived path that find and exec resolve to. Two pulls of the same digest are safe to run concurrently.

push

Publishes a package bundle to the registry. A candidate symlink is created locally after a successful push.

Usage

ocx package push [OPTIONS] <IDENTIFIER> <CONTENT>

Arguments

• <IDENTIFIER>: Package identifier including the tag, e.g. cmake:3.28.1_20260216120000.
• <CONTENT>: Path to the package bundle (.tar.xz) to publish.

Options

• -p, --platform <PLATFORM>: Target platform of the package (required).
• -c, --cascade: Cascade rolling releases. When set, pushing cmake:3.28.1_20260216120000 automatically re-points the rolling ancestors (cmake:3.28.1, cmake:3.28, cmake:3, and cmake:latest if applicable) to the new build — only if this is genuinely the latest at each specificity level. See tag cascades.
• -n, --new: Declare this as a new package that does not exist in the registry yet. Skips the pre-push tag listing that is otherwise used for cascade resolution.
• -m, --metadata <PATH>: Path to the metadata file. If omitted, ocx looks for a sidecar file next to the bundle.
• -h, --help: Print help information.

describe

Pushes package description metadata (title, description, keywords, README, logo) to the registry.

Usage

ocx package describe [OPTIONS] <IDENTIFIER>

Arguments

• <IDENTIFIER>: Package identifier (repository only; tag is ignored).

Options

• --readme <PATH>: Path to a README markdown file.
• --logo <PATH>: Path to a logo image (PNG or SVG).
• --title <TITLE>: Short display title for the package catalog.
• --description <TEXT>: One-line summary.
• --keywords <LIST>: Comma-separated search keywords.
• -h, --help: Print help information.

At least one of the above metadata options must be provided.

info

Displays description metadata for a package from the registry.

Usage

ocx package info [OPTIONS] <IDENTIFIER>

Arguments

• <IDENTIFIER>: Package identifier (repository only).

Options

• --save-readme <PATH>: Save the README to a file or directory.
• --save-logo <PATH>: Save the logo to a file or directory.
• -h, --help: Print help information.