Installation

Quick Install

The install scripts download the latest ocx binary from GitHub Releases, verify its SHA-256 checksum, and place it under ~/.ocx. They also configure your shell so that ocx is available on PATH in new terminals.

Shell

curl -fsSL https://ocx.sh/install.sh | sh

PowerShell

irm https://ocx.sh/install.ps1 | iex

PowerShell 7.4+ required

install.ps1 hard-fails on PowerShell earlier than 7.4 — it calls APIs introduced in that release and exits immediately with an error. Windows ships with Windows PowerShell 5.1, which is not supported. Install PowerShell 7.4 or later from aka.ms/install-powershell before running the script.

After installation, open a new terminal and verify:

ocx about

Skip shell profile modification

If you manage your PATH manually — for example, in a CI environment or a dotfile framework — pass --no-modify-path to prevent the installer from touching your shell profile:

curl -fsSL https://ocx.sh/install.sh | sh -s -- --no-modify-path

You can also set OCX_NO_MODIFY_PATH=1 as an environment variable. Either way, add ~/.ocx/symlinks/ocx.sh/ocx/cli/current/content/bin to your PATH yourself.

GitHub Releases

Pre-built binaries for all supported platforms are published to GitHub Releases. Download the archive for your platform, extract it, and place the ocx binary somewhere on your PATH.

Platform	Architecture	Archive
Linux	x86_64	ocx-x86_64-unknown-linux-gnu.tar.xz
Linux	aarch64	ocx-aarch64-unknown-linux-gnu.tar.xz
Linux (static)	x86_64	ocx-x86_64-unknown-linux-musl.tar.xz
Linux (static)	aarch64	ocx-aarch64-unknown-linux-musl.tar.xz
macOS	Apple Silicon	ocx-aarch64-apple-darwin.tar.xz
macOS	Intel	ocx-x86_64-apple-darwin.tar.xz
Windows	x86_64	ocx-x86_64-pc-windows-msvc.zip
Windows	ARM64	ocx-aarch64-pc-windows-msvc.zip

Each release also includes a sha256sum.txt file for checksum verification.

Manual install example (Linux x86_64)

# Download the archive and checksums
curl -LO https://github.com/ocx-sh/ocx/releases/latest/download/ocx-x86_64-unknown-linux-gnu.tar.xz
curl -LO https://github.com/ocx-sh/ocx/releases/latest/download/sha256sum.txt

# Verify checksum
sha256sum --check --ignore-missing sha256sum.txt

# Extract and move into place
tar xf ocx-x86_64-unknown-linux-gnu.tar.xz
install -m 755 ocx-x86_64-unknown-linux-gnu/ocx ~/.local/bin/ocx

The musl builds are fully statically linked

The musl variants have no runtime dependency on glibc. Use them in Alpine containers, minimal Docker images, or any environment where libc compatibility is uncertain.

Old wget (<1.17) is rejected by install.sh

install.sh fails closed when only an older wget is available — the strict TLS flags it relies on were added in wget 1.17 (2015), and downgrading would silently weaken the download integrity check. Alpine edge and some minimal Docker base images still ship older builds. If you hit this, either install a newer wget (apk add --upgrade wget on Alpine) or use the curl form of the install pipeline shown above — curl is the default and always works when present.

Pinned Install

When a CI pipeline needs to run the same ocx build on every runner — regardless of when it runs or who triggers it — pass a version to ocx self setup. The version can be a tag, a content digest, or both:

# Pin by tag (resolves once, installs that release):
ocx self setup 0.9.2

# Pin by tag and assert the exact content (immutability assertion):
ocx self setup 0.9.2@sha256:ab12cd34ef56...

The tag@digest form is the strongest guarantee: if the tag ever resolves to different content — for example because a digest was republished — the command fails with exit 65 and names both digests. No silent drift.

Digest pins are platform-specific

A sha256: digest pin selects the platform-specific package digest — the same tag resolves to a different digest on each OS and architecture. For CI matrices, pin by tag (each runner resolves its own platform digest), or supply a per-platform digest map; never share one digest value across different platforms.

To get the digest for a version you trust, capture it from a prior run's JSON output:

digest=$(ocx --format json self setup 0.9.2 | jq -r .bootstrap.digest)
# Then write the full pin into your CI config:
echo "ocx self setup 0.9.2@$digest"

That digest round-trips: the next ocx self setup 0.9.2@<digest> call succeeds immediately (already_present) if the same version is already installed, or downloads and verifies the exact content otherwise.

Under --frozen, a tag-only pin resolves from the local index (exit 81 if the tag is absent); a digest-only pin works when the blobs are already cached locally. Both modes are suitable for hermetic CI environments where the index is pre-populated.

Updating

Once ocx is installed, it can manage its own updates. Refresh the local index to discover new versions, then install and select the latest:

ocx index update ocx/cli
ocx package install --select ocx.sh/ocx/cli

Alternatively, re-run the install script — it always fetches the latest release:

Shell

curl -fsSL https://ocx.sh/install.sh | sh

PowerShell

irm https://ocx.sh/install.ps1 | iex

Pin a specific version

To install a specific version instead of the latest, pass --version (Shell) or set $Version (PowerShell) — see the examples below.

Shell

curl -fsSL https://ocx.sh/install.sh | sh -s -- --version 0.5.0

PowerShell

& { $Version = '0.5.0'; irm https://ocx.sh/install.ps1 | iex }

Verify Installation

ocx about prints the installed version, supported platforms, and detected shell:

ocx about

Dev Builds

Binaries published from the deploy-dev workflow carry a channel: dev field and a version string with a build-metadata suffix, such as 0.3.2-dev+20260528143045. These are pre-release snapshots, not stable releases.

To identify whether your installed binary is a dev build, run:

ocx version --verbose

The channel: dev line appears in the verbose output when present. For scripting use:

ocx --format json version | jq .channel

This returns "dev" for dev builds and null (field absent) for stable releases. Include this output when filing bug reports — it helps distinguish issues introduced between stable releases.

Uninstalling

To completely remove ocx and all installed packages, delete the data directory (default ~/.ocx, or whatever OCX_HOME points to):

Shell

rm -rf "${OCX_HOME:-$HOME/.ocx}"

PowerShell

Remove-Item -Recurse -Force $(if ($env:OCX_HOME) { $env:OCX_HOME } else { "$env:USERPROFILE\.ocx" })

Then remove the shell integration line from your profile (look for any line containing .ocx/env — the current installer wraps it in an existence check so that removing ~/.ocx/ alone no longer errors on shell startup, but any previously-added unguarded line should still be removed):

• bash: remove the .ocx/env source line from ~/.bash_profile or ~/.profile
• zsh: remove the .ocx/env source line from ~/.zprofile
• fish: delete ~/.config/fish/conf.d/ocx.fish
• nushell: delete ~/.local/share/nushell/vendor/autoload/ocx.nu
• elvish: remove the # BEGIN ocx / # END ocx block from ~/.config/elvish/rc.elv
• PowerShell: remove the .ocx\env.ps1 source line from your $PROFILE

This deletes everything

This removes all installed packages, the local index cache, and ocx itself. If you only want to remove specific packages, use ocx uninstall --purge and ocx clean instead.

Next Steps

• Getting Started — install your first package, switch versions, and set up shell integration.
• User Guide — the three-store architecture, versioning, locking, and authentication for private registries.
• Environment Reference — all environment variables ocx reads, including OCX_HOME for custom data directories.