ocx

Appearance

Environment ​

Primer ​

Truthy Values ​

Some OCX options can be configured using environment variables instead of command line flags. For example, the --offline flag can be set by configuring the OCX_OFFLINE environment variable to a truthy value. Truthy values are case-insensitive and include:

  • 1
  • y
  • yes
  • on
  • true

for enabling an option, and

  • 0
  • n
  • no
  • off
  • false

for disabling an option.

Internal ​

OCX_AUTH_<REGISTRY>_TYPE ​

The authentication type for the registry.

Valid values are:

  • basic
  • token (or bearer)
  • anonymous

OCX_AUTH_<REGISTRY>_USER ​

Configures the username for the registry when using basic authentication. The corresponding password should be configured using the OCX_AUTH_<REGISTRY>_TOKEN variable.

This value is ignored if the OCX_AUTH_<REGISTRY>_TYPE is not set to basic.

OCX_AUTH_<REGISTRY>_TOKEN ​

Configures the access token for the registry. For basic authentication, this value will be used as the password.

This value is ignored if the OCX_AUTH_<REGISTRY>_TYPE is not set to bearer or basic.

OCX_DEFAULT_REGISTRY ​

The default registry to use when no registry is specified in a package reference on the command line. If not set, OCX will default to ocx.sh.

WARNING

This variable is mostly intended for testing. It is recommended to specify the registry explicitly in the package reference.

OCX_HOME ​

The root directory for all OCX data — the object store, local index, and install symlinks. If not set, defaults to ~/.ocx.

sh
export OCX_HOME="/opt/ocx"

OCX_INDEX ​

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

sh
export OCX_INDEX="/path/to/bundled/index"

This variable is intended for environments where the index snapshot is bundled alongside a tool rather than stored in OCX_HOME — for example inside a GitHub Action, Bazel Rule, or DevContainer Feature.

The command line option --index takes precedence over this variable. This variable has no effect when --remote or OCX_REMOTE is set.

OCX_INSECURE_REGISTRIES ​

A comma-separated list of registry hostnames (with optional port) that should be contacted over plain HTTP instead of HTTPS.

sh
export OCX_INSECURE_REGISTRIES="localhost:5000,registry.local:8080"

WARNING

This variable disables TLS for the listed registries. Only use it for local development registries that do not support HTTPS.

OCX_LOG ​

The log level for OCX. You can set this variable to the same values as the --log-level command line option (e.g. warn, info, etc.). If --log-level is specified, it will take precedence over this environment variable. For more information on log levels, see the command line reference.

OCX_LOG_CONSOLE ​

Similar to OCX_LOG, but specifically for configuring the log level of messages emitted to the console. If OCX_LOG_CONSOLE is set, it will take precedence over OCX_LOG for console messages.

OCX_NO_UPDATE_CHECK ​

When set to a truthy value, OCX will not check the remote registry for newer versions on CLI startup. By default, OCX prints a notice to stderr if a newer version is available in the remote registry.

The update check is also automatically suppressed when:

  • CI is set to a truthy value
  • OCX_OFFLINE is set to a truthy value (or --offline flag)
  • stderr is not a terminal (e.g., piped or redirected)
  • the command is version, info, or shell completion

OCX_NO_MODIFY_PATH ​

When set to a truthy value, the install scripts (install.sh and install.ps1) will skip modifying shell profile files. Use this in CI environments or when you manage your PATH manually.

The command line option --no-modify-path on the install scripts has the same effect.

OCX_NO_CODESIGN ​

When set to a truthy value, OCX will skip ad-hoc code signing of macOS binaries after installation. By default, OCX automatically applies ad-hoc code signatures to extracted Mach-O binaries on macOS, which is required for execution on Apple Silicon. See the FAQ for details on why this is necessary and how it works.

This variable has no effect on non-macOS systems.

OCX_OFFLINE ​

When set to a truthy value, OCX will run in offline mode, which will not attempt to fetch any remote information. The command line option --offline takes precedence over this variable.

OCX_REMOTE ​

When set to a truthy value, OCX will use the remote index by default instead of the local index.

External ​

CI ​

When set to a truthy value, OCX suppresses the update check on startup. Most CI systems (GitHub Actions, GitLab CI, Travis, etc.) set this automatically.

GITHUB_ACTIONS ​

Set to true by GitHub Actions runners. Used by ocx ci export to auto-detect the CI flavor. When detected, the command writes environment variable exports to the files specified by GITHUB_PATH and GITHUB_ENV.

GITHUB_PATH ​

Set by GitHub Actions to a file path. ocx ci export appends PATH entries to this file, making them available in subsequent workflow steps.

GITHUB_ENV ​

Set by GitHub Actions to a file path. ocx ci export appends non-PATH environment variables to this file using KEY=value syntax (or heredoc delimiters for multiline values).

DOCKER_CONFIG ​

The location of the Docker configuration directory. Read by the Docker credential helper that ocx delegates to when resolving registry credentials from ~/.docker/config.json.

NO_COLOR ​

When set to any non-empty value, disables ANSI color output. This is a cross-tool convention for respecting user color preferences. The --color flag takes precedence.

CLICOLOR ​

When set to 0, disables color output. Part of the CLICOLOR convention.

CLICOLOR_FORCE ​

When set to a non-zero value, forces color output even when stdout is not a terminal. Overrides CLICOLOR but is itself overridden by NO_COLOR.

RUST_LOG ​

A fallback for configuring the log level of OCX and its dependencies. If OCX_LOG is not set, OCX will respect the log level configured via RUST_LOG. The format for this variable is the same as for OCX_LOG.