- docs
- Look things up
- Look things up
- Reference
- Environment
Environment
Every variable OCX reads, sets or lists as external, public ones first, linking the root flag a variable stands in for; test seams are excluded. ocx-mirror documents its own variables.
Truthy values
A boolean variable reads these spellings in any case.
| Reads as | Spellings |
|---|---|
| On | 1, y, yes, on, true |
| Off | 0, n, no, off, false |
- Strict:
OCX_OFFLINE,OCX_FROZEN,OCX_NO_CONSENTandOCX_NO_VERIFYexit 78 naming the variable on any other value. - Lenient: every other boolean variable logs a warning and uses its default.
OCX_ALLOW_YANKED
Boolean — allow a tag resolving to a yanked index entry. Forwarded to child OCX.
Without it a tag resolve against a yanked entry of the public index exits 65. This holds online and against a local copy with no network.
ocx index update does not bypass it. A digest-pinned reference never needs it, and a project resolved from ocx.lock is unaffected by a yank.
- Audience: public
- Value:
bool - See: Public index
OCX_ANNOUNCE_GIT_TOKEN
The push-only forge credential (the secret half of git push’s Basic pair).
Used only under --transport git, for every git call to the index remote; REST reads keep
using OCX_ANNOUNCE_TOKEN. Unset or empty reuses the resolved API credential.
Sent as the Basic password via git’s config environment, never in a URL, argv or
.git/config; the user half is OCX_ANNOUNCE_GIT_USERNAME. Stripped from plugin-dispatched
children and from any environment OCX writes, unlike the API half.
- Audience: public
- Value:
string - See: Announce from CI
OCX_ANNOUNCE_GIT_USERNAME
The user half of the git write transport’s Basic pair, default gitlab-ci-token; a value containing :, and an empty one, fall back to the default.
Not a credential, so plugins inherit it from the ambient environment.
- Audience: public
- Value:
string - See: Announce from CI
OCX_ANNOUNCE_TOKEN
The API half of the forge credential pair (a forge access token).
Read by ocx package announce and ocx package claim to open or update a pull or merge
request; --output needs none. GitHub needs repo scope, GitLab api.
Under --transport git it authenticates only the REST calls and OCX_ANNOUNCE_GIT_TOKEN
carries the push. In a GitLab job an unset token falls through to CI_JOB_TOKEN, which cannot
write through the API.
- Audience: public
- Value:
string - See: Announce from CI
OCX_AUTH_<REGISTRY>_TOKEN
Registry token for one registry; <REGISTRY> is the registry slug.
The bearer token, or the password for basic; ignored unless the type is bearer or basic.
- Audience: public
- Value:
string - See: Authenticate with a private registry
OCX_AUTH_<REGISTRY>_TYPE
Authentication type for one registry.
<REGISTRY> is the registry name with every non-alphanumeric character replaced by _, case
kept, so docker.io reads OCX_AUTH_docker_io_TYPE.
Any OCX_AUTH_* value set for a registry means OCX never invokes a Docker credential helper
for it; anonymous opts a registry out of helper lookup entirely.
- Audience: public
- Value:
choice: anonymous, basic, token, bearer - See: Authenticate with a private registry
OCX_AUTH_<REGISTRY>_USER
User name for one registry; <REGISTRY> is the registry slug.
Read for the basic type only; ignored for any other type.
- Audience: public
- Value:
string - See: Authenticate with a private registry
OCX_BINARY_PIN
Absolute path to the running ocx, set on every spawn so a child OCX runs the same binary, not whatever $PATH resolves.
Set by OCX on every subprocess it spawns, so the inner ocx launcher exec of a generated
launcher runs the binary that installed the package. Unset, launchers fall back to
$PATH-resolved ocx; set it by hand only to pin a specific binary.
The Windows .exe shim treats a defined but empty value as defined, the Unix launcher’s
${OCX_BINARY_PIN:-ocx} as unset. The value is the installed ocx path when the running
binary is that one and the path is safely owned, else the running binary; never empty.
- Audience: public
- Value:
path - See: Launcher forwarding
OCX_CEILING_PATH
Path at which the CWD walk for a project ocx.toml stops; relative values join onto the working directory. An explicit --project or OCX_PROJECT is not bounded by it.
The walk probes the ceiling directory and never ascends above it, so a project file there is
found and one in a parent is not. It already stops at the first .git entry; this bounds it
where no repository marks the edge, such as a CI workspace under a shared parent.
- Audience: public
- Value:
path - See: ocx.toml in depth
OCX_CONFIG
Paths to explicit configuration files, separated like PATH (: on Unix, ; on Windows). Mirrors --config, which takes one path.
Each file layers on the discovered chain and the managed tier in list order, a later file
winning on conflicting scalars; --config loads after the whole list. At most 32 files.
A missing file is an error naming it; an empty value is unset and empty entries are skipped. A path containing the separator cannot be listed.
With OCX_NO_CONFIG the listed files still load.
- Audience: public
- Value:
path_list - Flag:
--config
OCX_CONSENT_NAMESPACES
Comma-separated OCI namespaces; a project whose whole lock names sources inside them activates without a directory grant or a consent stamp.
Each token is <registry>/<first-path-segment>, with or without a trailing /*; there is
no whole-registry token, and one malformed token discards the whole variable with a warning.
Additive with [shell.consent] namespaces.
The match is against the store’s record of the coordinate each digest was pulled under on
this machine. It is not against the lock text, and it never covers a project’s own [env]
table.
- Audience: public
- Value:
string - See: Consent grammar
OCX_CONSENT_PATHS
Project directories (separated like PATH) the per-prompt shell hook may activate in without a consent stamp, subtrees included.
An entry is an exact canonicalized directory, or with a trailing /* that directory and
everything beneath it.
- Audience: public
- Value:
path_list - See: Consent grammar
OCX_DEFAULT_REGISTRY
The registry a bare identifier resolves under; outranks [registry] default, else ocx.sh. Empty is unset.
Forwarded so every frame of a launch chain agrees.
Environment-only: no CLI flag, so the forwarded value is the one this invocation read. An empty value clears an inherited setting rather than travelling onward.
- Audience: public
- Value:
string - See: Configure OCX defaults
OCX_EXTRA_CA_CERTS
Extra CA roots — a path or inline PEM (contains -----BEGIN); empty is unset.
Adds trust for registry, index, forge and Sigstore clients on top of the host store and
compiled-in roots. Wins over every config.toml tier unless the extra_ca_certs pair is
system-locked, when it is ignored with a warning.
A failure still reports UnknownIssuer (exit 69). On Windows an inline PEM can hit
cmd.exe’s 8,191-character limit; use a path.
- Audience: public
- Value:
path_or_pem - See: Proxy and corporate CA
OCX_FROZEN
Boolean — a tag-only reference missing from the local index errors instead of being fetched; digest-pinned content still fetches. Mirrors --frozen.
A tag in the local index resolves from cache; a digest or ocx.lock pin still fetches. An
unpinned tag missing from it exits 81, as does a frozen ocx index update.
Unlike OCX_OFFLINE it is not a network ban; patch companions and the managed-config tier
are unaffected. The flag takes precedence; combining with OCX_REMOTE is a usage error
(exit 64), with OCX_OFFLINE offline wins.
- Audience: public
- Value:
bool - Flag:
--frozen
OCX_GLOBAL
Withdrawn — no longer read; pass --global instead.
A set value is never honoured. Each process prints one notice naming --global and carries on, so a leaked environment keeps working.
The name stays declared until 0.7 only as the target of that notice.
- Audience: public
- Value:
bool
OCX_HOME
The OCX data root — $OCX_HOME, else ~/.ocx.
Forwarded set-always as the resolved root, or an ocx exec --clean child (no HOME)
resolves another root and misses the package the parent just materialized. The files
ocx self setup writes may export it.
The project walk skips an ocx.toml sitting exactly here. That file is the global
toolchain manifest, reached only through --global, never by upward discovery.
- Audience: public
- Value:
path - See: Storage
OCX_IDENTITY_TOKEN
OIDC bearer token for keyless signing, below --identity-token-file/-stdin.
Used by ocx package sign and ocx package attest only when neither
--identity-token-file nor --identity-token-stdin is given; ambient CI detection and
browser OAuth rank below it. Never forwarded or logged, and stripped from plugin-dispatched
children and from any environment OCX writes.
A short-lived JWT (typically under 10 minutes): fetch a fresh one just before signing.
- Audience: public
- Value:
string - See: Sign a release
OCX_INDEX
Path to the local index directory. Mirrors --index.
Swaps the whole local index collection (default $OCX_HOME/index/) for a shipped one, never a partial overlay. It is meant for a bundled copy in a GitHub Action, Bazel rule or devcontainer.
--index takes precedence.
Under --remote or OCX_REMOTE, tag- and catalog-addressed lookups bypass it, while
digest-addressed lookups still consult it first.
- Audience: public
- Value:
path - Flag:
--index
OCX_INSECURE_REGISTRIES
Comma-separated host[:port] authorities that may be dialled over plain HTTP.
Forwarded, or a child with a narrower set cannot reach a registry the parent just pulled from.
Union with [registries.<name>] insecure; only a system-tier insecure = false subtracts.
Names match exactly as host[:port].
Also gates plain http:// [mirrors] targets. Credentials travel in the clear; an HTTPS
registry naming an http token realm, or redirected to http://, is still refused.
- Audience: public
- Value:
host_list - See: Use a corporate mirror
OCX_JOBS
Maximum number of root packages pulled in parallel.
Applies to every command that fans out through the package manager (install, pull,
package pull, exec, env). 0 uses all logical cores, unlike Cargo’s --jobs 0 which
errors.
Negative or non-numeric values are ignored with a warning; unset is unbounded. --jobs
takes precedence.
- Audience: public
- Value:
integer - Flag:
--jobs
OCX_KEY_PASSWORD
Password for an encrypted signing key; never a flag, since argv is visible host-wide.
Pair it with --key <path> or OCX_SIGNING_KEY; it opens a key and never names one. An unset variable reads as the empty password.
That is the shape of a pair made by pressing enter twice in cosign generate-key-pair, so that case is supported rather than an error.
Stripped from plugin-dispatched children and from any environment OCX writes. OCX does not generate key pairs.
- Audience: public
- Value:
string - See: Sign a release
OCX_LAZY_MODE
Lazy materialization mode (never / always), the weakest tier of the lazy-mode ladder.
Not forwarded: it changes when content materializes, never which digest resolves.
never (default) composes eagerly, always composes a shim that defers the download to
first invocation. Case-insensitive, unlike the --lazy-mode flag and the ocx.toml key.
An unrecognized value is ignored with a warning. Overridden by the --lazy-mode flag,
[package."<id>"], [group.<name>] and the top-level lazy-mode key.
- Audience: public
- Value:
choice: never, always - See: Deferred packages
OCX_LAZY_REPORT
Lazy materialization report (silent / progress); not forwarded, like OCX_LAZY_MODE.
silent (default) or progress, case-insensitive. progress opens a channel on the controlling terminal only when the first-invocation download actually happens.
It falls back to silent where no terminal is reachable (Docker build, CI, setsid).
Read inside ocx launcher shim, never by the composing command. Overridden by
--lazy-report, [package."<id>"] and the top-level key; there is no group tier.
- Audience: public
- Value:
choice: silent, progress - See: Deferred packages
OCX_LOG_CONSOLE
Log level for console messages only; outranks OCX_LOG_LEVEL there.
- Audience: public
- Value:
string - See:
--log-level
OCX_LOG_LEVEL
Log level, as --log-level accepts it; the flag wins. Defaults to info.
- Audience: public
- Value:
string - Flag:
--log-level
OCX_MANAGED_CONFIG
OCI reference overriding [managed].source for this invocation only; empty is unset, OCX_NO_CONFIG suppresses it. Forwarded to child OCX.
Never written back to the seed; only ocx config setup and
ocx self setup --managed-config write it. Resolving the tier never fetches: pair the variable with an
explicit ocx config update in CI.
Forwarded to children. Suppressed entirely by OCX_NO_CONFIG.
- Audience: public
- Value:
string - See: Manage configuration for a fleet
OCX_MIRRORS
JSON object mapping an upstream host to a mirror string or {"registry"?, "index"?}, the same union [mirrors."<host>"] accepts. Forwarded to child OCX.
A string value redirects both the registry and index roles; the object form splits them.
A role value is scheme://host[/repo-key-prefix].
Replaces the [mirrors] entry per host and per role; unlike a config-file registry entry
it cannot drop a namespace off the compiled-in index. A malformed value (bad JSON, wrong
shape, http:// for a host not plaintext-eligible) aborts at startup.
- Audience: public
- Value:
json - See: Use a corporate mirror
OCX_NO_CODESIGN
Boolean — skip ad-hoc code signing of macOS binaries after installation.
- Audience: public
- Value:
bool - See: Platform problems
OCX_NO_COMPLETION
Boolean — ocx self activate skips the shell-completion block.
PATH prepend and the global env eval still run. Use it when a framework such as oh-my-zsh
or a Nix completion store manages completions.
ocx shell completion without --if-enabled generates the script regardless; with it, this
variable is the first rung of the policy that decides whether anything prints.
- Audience: public
- Value:
bool - See: Shell integration
OCX_NO_CONFIG
Boolean — skip the discovered config-tier chain; every file --config and OCX_CONFIG name still loads and a system-tier lock survives. Forwarded to child OCX.
Also drops the [managed] snapshot and the OCX_MANAGED_CONFIG read. A system-tier policy
in /etc/ocx/config.toml still loads, filtered to its locked sections ([records] and
[telemetry] among them), and an unreadable system file still aborts (exit 78).
Env-only: there is no --no-config flag. Hermetic pattern:
OCX_NO_CONFIG=1 ocx --config /ci/ocx.toml ....
- Audience: public
- Value:
bool - See: Configuration
OCX_NO_CONFIG_REFRESH
Boolean — kill switch for the managed-config background refresh; ocx config update still works.
Forwarded, or a child’s refresh replaces the managed tier with config the parent never saw.
Silences both the apply and notify postures of the background tick. ocx config update
still runs; ocx self setup and ocx config setup still re-sync an adopted seed regardless
(use --offline to skip that).
The tick is also off when CI is truthy, OCX_OFFLINE is set or stderr is not a terminal.
Distinct from OCX_NO_UPDATE_CHECK, which covers the OCX self-update notice.
- Audience: public
- Value:
bool - See: Managed configuration
OCX_NO_CONSENT
Boolean — commands that stamp shell-activation consent as a side effect write none; --consent / --no-consent outrank it and ocx shell allow ignores it.
Forwarded, else a script run by ocx exec that calls ocx pull stamps after all.
Covers add, remove, lock, update, upgrade, pull, exec and init.
ocx exec --no-consent sets it on the child too; --consent does not clear it.
Set it in a pipeline or image, not an interactive profile: exported globally, growing a lock past the stamped sources leaves the project inert.
- Audience: public
- Value:
bool - See: Consent grammar
OCX_NO_HOOK
Boolean — disables the per-prompt shell hook; ocx self activate still runs at shell start.
ocx self activate still prepends PATH, loads completions and evals the global env, but
registers no per-prompt hook. Read once at shell start, so exporting it mid-session takes
effect at the next shell.
The only variable that makes a shell wholly inert: OCX_NO_CONFIG leaves explicit
--config files and the consent grants active. Boolean, not tri-state; --hook is the
positive channel.
- Audience: public
- Value:
bool - See: Shell integration
OCX_NO_MODIFY_PATH
Boolean — ocx self setup modifies no shell profile. Mirrors --no-modify-path.
Suppresses both PATH surfaces on every platform, the managed profile blocks and the
session-level registration; each location still shows in the summary as skipped_opt_out.
Second rung of the ladder: --no-modify-path, this variable, [shell] modify_path, then
allowed.
The opt-out persists as modify_path = false; there is no positive flag. Only truthy values
enable it.
- Audience: public
- Value:
bool - Flag:
--no-modify-path
OCX_NO_PROJECT
Boolean — skip the CWD walk and OCX_PROJECT; explicit --project paths still load.
Skips the CWD walk and ignores OCX_PROJECT; explicit --project still loads. Env-only: no
--no-project flag.
Forwarded so children also skip discovery. Hermetic pattern:
OCX_NO_PROJECT=1 ocx --project /ci/ocx.toml exec -- ....
- Audience: public
- Value:
bool - See: ocx.toml in depth
OCX_NO_UPDATE_CHECK
Boolean — kill switch for the background self-update and toolchain drift checks; forwarded to child OCX.
The checks are also off when CI is truthy, OCX_OFFLINE is set, stderr is not a terminal, or the command is version, about or shell completion. The drift notice additionally skips update, lock, add, remove and init.
This variable also suppresses the throttle state write.
Distinct from OCX_NO_CONFIG_REFRESH, which silences only the managed-config tick.
- Audience: public
- Value:
bool - See: Update or uninstall OCX
OCX_NO_VERIFY
Boolean — skip the policy-gated auto-verify on install/pull; --no-verify wins. Forwarded to child OCX.
Skips the policy-gated auto-verify on install, pull and every command that auto-installs on demand (exec, env, package exec, package env, patch discovery). Only install and pull carry the --verify / --no-verify flag, which outranks this variable.
A skipped package that publishers or a policy cover prints one warning: line per invocation.
With no publishers listed in the index and no [[trust.policy]] covering a package, verification does not run regardless.
- Audience: public
- Value:
bool - See: Verify what you install
OCX_OFFLINE
Boolean — disables network access when truthy. Mirrors --offline.
Tag-to-digest resolution must come from the local index or a digest pin; an unpinned tag
missing locally errors immediately. --offline takes precedence.
With OCX_REMOTE it is pinned-only mode. For ocx package verify it scopes to the Sigstore trust services (Rekor key, TUF), not the registry.
It needs a pinned Rekor key from a trust-root rung or the cache. Without one it exits 81 and never skips verification.
- Audience: public
- Value:
bool - Flag:
--offline
OCX_PATCHES
JSON object encoding the resolved [patches] config; forwarded only when configured.
- Audience: public
- Value:
json - See: Patch packages for your infrastructure
OCX_PATCH_SNAPSHOT
Path to the patch snapshot file ocx patch freeze writes, whose pinned digests win over live tag lookups. Forwarded to child OCX.
While set, every command but ocx patch sync (refused, exit 78) and ocx patch freeze uses
only the snapshot’s pinned digests and records no pin. A companion the snapshot omits is
absent, and a required one fails with exit 79, as does a missing pinned blob under
--offline.
A format version this OCX cannot read exits 65. Independent of --frozen; ocx clean roots
the snapshot’s companions only while this is set.
- Audience: public
- Value:
path - See: Patch packages for your infrastructure
OCX_PROJECT
Path to an explicit project ocx.toml. Mirrors --project.
A file loads directly and a directory resolves to <dir>/ocx.toml. Precedence: --project,
this variable, the CWD walk; OCX_NO_PROJECT prunes the last two.
A path that does not exist exits 79, a directory with no ocx.toml exits 64, an unreadable
one exits 74. Empty is unset.
Explicit paths follow symlinks; the CWD walk rejects a symlinked ocx.toml.
- Audience: public
- Value:
path - Flag:
--project
OCX_QUIET
Boolean — suppresses the stdout report and the transfer progress bars.
- Audience: public
- Value:
bool - Flag:
--quiet
OCX_RECORDS_DIR
Directory execution records are written to; absent or empty turns recording off. Forwarded so every frame of a launch chain records into the outermost sink.
Equivalent to --records-dir on ocx exec and ocx package exec and to the
[records] dir key. Unset at every tier means no record and no added I/O.
Forwarded, so a launcher re-entry (ocx launcher exec, which takes no flags) writes to the
same sink. The flag overrides it; a system-tier [records] declaration locks the section
and this variable then has no effect.
- Audience: public
- Value:
path - See: Execution records
OCX_RECORDS_NAME
Filename template for each execution record; forwarded alongside OCX_RECORDS_DIR.
No OCX_RECORDS_REQUIRED exists: fail-closed recording is config-file-only operator policy.
Equivalent to --records-name and the [records] name key; the flag overrides it. The
placeholders are {time}, {pid}, {rand} and {host}; an unrecognized one is a
configuration error (exit 78), never a literal.
Needs a sink from OCX_RECORDS_DIR, --records-dir or [records] dir. Locked with the
rest of [records] under a system-tier policy.
- Audience: public
- Value:
string - See: Execution records
OCX_REMOTE
Boolean — uses the remote index by default when truthy. Mirrors --remote.
Routes tag list, catalog and tag resolution to the registry. Pure-query commands (
ocx index list, ocx index catalog, ocx package description pull) persist nothing; run
ocx index update to refresh the snapshot.
Digest-addressed reads still consult the local index first. --remote takes precedence.
- Audience: public
- Value:
bool - Flag:
--remote
OCX_SELF_UPDATE
RefreshPolicy wire value for OCX’s own update check; beats [update] self. Not forwarded.
notify (default) prints a notice naming ocx self update, apply installs the newer OCX
after the command finishes without changing its exit code, manual never checks. Lowercase
only; an unrecognized value is ignored at debug level and falls through.
Beats the config file. apply needs a terminal on stderr, CI unset, online, and
OCX_NO_UPDATE_CHECK unset, and does nothing for an OCX that ocx self setup did not
install.
- Audience: public
- Value:
choice: apply, notify, manual - See: Update or uninstall OCX
OCX_SIGNING_KEY
The signing key PEM itself, for --key env://OCX_SIGNING_KEY; any other env:// name works but is not scrubbed from plugins.
Holds the PEM, never a path: a cosign ENCRYPTED SIGSTORE PRIVATE KEY envelope when
signing, an SPKI public key when a [[trust.policy]] signer names it. For runners with no
writable disk.
Unset or empty exits 74 naming the variable; over 64 KiB exits 65. Stripped from plugin-dispatched
children and from any environment OCX writes; a key held in any other env:// name is inherited by plugins and launchers.
- Audience: public
- Value:
string - See: Sign a release
OCX_SIGSTORE_TRUSTED_ROOT
Path (bare or file://) to a Sigstore trusted-root JSON document, or a directory holding trusted_root.json, that ocx package verify loads its trust material from.
The --sigstore-trusted-root flag takes precedence. The root must carry the Fulcio CAs, the CT log keys and the
pinned Rekor key together; CA anchors alone are refused with exit 78.
Bypasses the TUF fetch, so keeping it current is the operator’s job.
With OCX_OFFLINE it is the fully offline path. Ladder after the flag: this variable,
[trust.sigstore], $OCX_HOME/sigstore/trusted-root.json, the cache, then TUF.
- Audience: public
- Value:
path - See: Self-hosted Sigstore
OCX_TELEMETRY
Switch for exporting usage telemetry; unset or empty defers to [telemetry] in config.
1, y, yes, on and true (ASCII case-insensitive) turn it on; 0, n, no, off
and false are an explicit off. Any other value, a non-UTF-8 one included, is an explicit
off plus one warning per run naming this variable and never the value, so a typo never
arms export and never defers to a file that could.
Forwarded to child OCX, so a nested run agrees with its parent.
- Audience: public
- Value:
tri_bool
OCX_TELEMETRY_HEADERS
Headers sent with every telemetry export, name=value[,name=value...]; values are percent-decoded and names trimmed.
Merges over [telemetry] headers per name, case-insensitively, except that a name a system-locked section sets wins. Sent only to a destination [telemetry] names, never to one the OTEL_EXPORTER_OTLP_* variables name.
A malformed value disables the export for the run with one warning that names this variable and never the value.
Stripped from plugin-dispatched children and from any environment OCX writes, so a nested
ocx under ocx exec does not see it; put a long-lived token in a config file instead.
- Audience: public
- Value:
string
OCX_TOOLCHAIN_ACTIVATE
Toolchain activation mode (env / bin / none), the weakest tier of the activate ladder. Not forwarded, like OCX_LAZY_MODE.
env composes the toolchain environment every prompt (default), bin puts the home’s
active/bin on PATH only, none withdraws what OCX owns. Case-insensitive, not trimmed.
An unrecognized value warns and falls through to the next tier; the ocx.toml key is a
parse error (exit 78). Sits below the ocx.toml activate key.
- Audience: public
- Value:
choice: env, bin, none - See: Toolchain activation
OCX_TOOLCHAIN_DIR
Root under which project toolchain homes render — the env tier of toolchain_dir.
Weakest tier: config.toml wins. A refused root exits 78.
- Audience: public
- Value:
path - See: ocx.toml in depth
OCX_TOOLCHAIN_PINNED
Boolean — composed paths pin to digest roots; the weakest tier of the pinned ladder.
Unset and an explicit false are different answers. Below --pinned / --no-pinned and
the ocx.toml pinned key.
True names the digest roots ocx.lock pins, so a later ocx update does not reach that
environment; false follows the rendered links/<group>/<entry> links, the default.
A root entry whose link is absent or stale composes on its digest path; dependency paths always do. An unparseable value warns and falls through.
- Audience: public
- Value:
tri_bool - See: Toolchain activation
OCX_TOOLCHAIN_UPDATE
RefreshPolicy wire value for the toolchain drift check; beats [update] toolchain. Not forwarded.
notify (default) prints one stderr line per toolchain file with drift, naming
ocx update; apply is read as notify, since only ocx update moves a pin; manual never
checks. Lowercase only; other values are ignored at debug level.
The check compares the lock’s platform digests with the registry without writing the local index. It probes a project only when it is consented.
It stays silent on a missing or stale lock, a registry error or a 5-second timeout.
- Audience: public
- Value:
choice: apply, notify, manual - See: Update or uninstall OCX
OCX_UPDATE_CHECK_INTERVAL
Throttle interval of the background update checks, \d+[smhd]? (bare digits = seconds).
Beats [update] interval. Not forwarded: a personal preference, like OCX_LAZY_MODE.
Unset means 1d; 0 checks on every eligible invocation; units are s, m, h, d. Surrounding whitespace is trimmed.
An invalid value is logged at debug level and falls through to [update] interval.
The check waits for a registry round trip and never fails the command. It is also suppressed
when stderr is not a terminal or CI is set, whatever the interval; ocx self update
always bypasses it.
- Audience: public
- Value:
string - See: Update or uninstall OCX
Internal
Variables OCX writes and reads for its own plumbing. Do not set them by hand unless an entry says so.
__OCX_CREDENTIAL_HELPER
Set by OCX on every credential helper it starts until 0.7; an OCX running under it never downloads.
A helper installed through OCX is a trampoline that starts ocx exec; without the marker that
OCX would install the package the outer OCX is still pulling and wait on its lock. Under the
marker OCX behaves as if --offline were given.
- Audience: plumbing
- Value:
bool
__OCX_ENV_PWD
Elvish only: the recording shell’s pid and $pwd, so the hook re-runs on a directory change.
Holds the pid, $pwd, the direnv/mise yield sentinels and the two consent-grant variables,
space-joined; never set it by hand.
- Audience: plumbing
- Value:
string
__OCX_ENV_STATE
The execution state: what OCX last applied to the shell, and the policy a parent OCX passed down.
The transport state: it tells a value OCX wrote from one you typed, and a child OCX reads it to see what the shell applied. Crossing into the interactive shell makes it a user-facing contract despite the private name.
unset __OCX_ENV_STATE (unset-env in elvish) means forget: the next prompt starts over and leaves the applied values in place.
A reader refuses any applied record on a credential key or an OCX_AUTH_* key, because reverting a
forged record would drop your credential. Reserved: a package cannot declare it and --env cannot set it.
- Audience: plumbing
- Value:
string
__OCX_ENV_STOOD_DOWN
A hook-local copy of a stood-down __OCX_ENV_STATE, never transported.
Kept by a shell hook that cannot hold an unexported variable across prompts (elvish); removed at every projected spawn, so it never reaches a child. Never set it by hand.
- Audience: plumbing
- Value:
string
External
Variables set by the system or by other tools, which OCX reads.
ACTIONS_ID_TOKEN_REQUEST_TOKEN
Bearer token for ACTIONS_ID_TOKEN_REQUEST_URL.
- Audience: foreign
- Value:
string
ACTIONS_ID_TOKEN_REQUEST_URL
URL the runner serves OIDC tokens from.
- Audience: foreign
- Value:
string
ALL_PROXY
Proxy URL for every scheme.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
CI
Set by most CI providers. When truthy, the background update check and the managed-config refresh are skipped; see OCX_NO_UPDATE_CHECK and OCX_NO_CONFIG_REFRESH.
- Audience: foreign
- Value:
bool - See: Run OCX unattended in a pipeline
CIRCLE_OIDC_TOKEN_V2
CircleCI OIDC token.
- Audience: foreign
- Value:
string
CI_COMMIT_SHA
Commit the GitLab pipeline runs on.
- Audience: foreign
- Value:
string
CI_JOB_ID
Id of the GitLab job; read as a telemetry attribute.
- Audience: foreign
- Value:
string
CI_JOB_NAME
Name of the GitLab job; read as a telemetry attribute.
- Audience: foreign
- Value:
string
CI_JOB_TOKEN
GitLab CI job token.
- Audience: foreign
- Value:
string
CI_JOB_URL
URL of the GitLab CI job.
- Audience: foreign
- Value:
string
CI_PIPELINE_CREATED_AT
Creation time of the GitLab pipeline.
- Audience: foreign
- Value:
string
CI_PIPELINE_ID
Id of the GitLab pipeline; read as a telemetry attribute.
- Audience: foreign
- Value:
string
CI_PROJECT_PATH
group/project path of the GitLab project.
- Audience: foreign
- Value:
string
CI_PROJECT_URL
URL of the GitLab project.
- Audience: foreign
- Value:
string
CLICOLOR
0 disables colour output.
- Audience: foreign
- Value:
string
CLICOLOR_FORCE
Non-0 forces colour output.
- Audience: foreign
- Value:
string
COMSPEC
Windows command interpreter; bare ocx shell runs it when the shell to open is cmd.
- Audience: foreign
- Value:
path
DIRENV_DIR
Set by direnv inside an allowed directory.
- Audience: foreign
- Value:
string
DOCKER_CONFIG
Docker credential-store directory, read by the credential helper.
- Audience: foreign
- Value:
path - See: Authenticate with a private registry
DO_NOT_TRACK
Console-do-not-track convention; a truthy value is honoured as an opt-out and turns telemetry export off.
- Audience: foreign
- Value:
bool
GITHUB_ACTIONS
true inside GitHub Actions.
- Audience: foreign
- Value:
bool
GITHUB_ACTOR
Login of the user that triggered the workflow.
- Audience: foreign
- Value:
string
GITHUB_ACTOR_ID
Numeric id of the user that triggered the workflow.
- Audience: foreign
- Value:
string
GITHUB_ENV
File GitHub Actions reads exported variables from.
- Audience: foreign
- Value:
path
GITHUB_JOB
Name of the GitHub Actions job; read as a telemetry attribute.
- Audience: foreign
- Value:
string
GITHUB_PATH
File GitHub Actions reads PATH additions from.
- Audience: foreign
- Value:
path
GITHUB_REPOSITORY
owner/repo of the workflow.
- Audience: foreign
- Value:
string
GITHUB_RUN_ID
Workflow run id.
- Audience: foreign
- Value:
string
GITHUB_SERVER_URL
GitHub server URL.
- Audience: foreign
- Value:
string
GITHUB_SHA
Commit the workflow runs on.
- Audience: foreign
- Value:
string
GITLAB_CI
true inside GitLab CI.
- Audience: foreign
- Value:
bool
GITLAB_USER_ID
Numeric id of the GitLab user that started the job.
- Audience: foreign
- Value:
string
GITLAB_USER_LOGIN
Login of the GitLab user that started the job.
- Audience: foreign
- Value:
string
GIT_SSL_CAINFO
CA bundle git uses.
- Audience: foreign
- Value:
path
GIT_SSL_CAPATH
CA directory git uses.
- Audience: foreign
- Value:
path
HOME
The user’s home directory.
- Audience: foreign
- Value:
path
HOMEDRIVE
Drive of the Windows home directory. Passed only to the git process ocx package announce runs; never used to derive paths.
- Audience: foreign
- Value:
string
HOMEPATH
Path of the Windows home directory below HOMEDRIVE. Passed only to the git process ocx package announce runs; never used to derive paths.
- Audience: foreign
- Value:
string
HTTPS_PROXY
HTTPS proxy URL.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
HTTP_PROXY
HTTP proxy URL.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
MISE_SHELL
Set by mise’s shell activation.
- Audience: foreign
- Value:
string
NO_COLOR
Disables colour output when set to any non-empty value.
- Audience: foreign
- Value:
string
NO_PROXY
Hosts reached without a proxy.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
OTEL_EXPORTER_OTLP_COMPRESSION
OTLP compression for every signal; not honoured, the request is never compressed.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_ENDPOINT
OTLP endpoint for every signal; honoured as the export destination when OTEL_EXPORTER_OTLP_LOGS_ENDPOINT is unset.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_HEADERS
OTLP headers for every signal; honoured only when OTEL_EXPORTER_OTLP_ENDPOINT names the destination and OTEL_EXPORTER_OTLP_LOGS_HEADERS is unset. Never sent to a [telemetry] endpoint.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
OTLP compression for logs; not honoured, the request is never compressed.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
OTLP endpoint for logs; honoured as the export destination, used verbatim.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_LOGS_HEADERS
OTLP headers for logs; honoured when an OTEL_EXPORTER_OTLP_* endpoint names the destination. Never sent to a [telemetry] endpoint.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
OTLP transport protocol for logs; honoured, default http/protobuf.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
OTLP export timeout for logs, in milliseconds; honoured.
- Audience: foreign
- Value:
integer
OTEL_EXPORTER_OTLP_PROTOCOL
OTLP transport protocol for every signal; honoured when OTEL_EXPORTER_OTLP_LOGS_PROTOCOL is unset, default http/protobuf.
- Audience: foreign
- Value:
string
OTEL_EXPORTER_OTLP_TIMEOUT
OTLP export timeout for every signal, in milliseconds; honoured when OTEL_EXPORTER_OTLP_LOGS_TIMEOUT is unset.
- Audience: foreign
- Value:
integer
OTEL_LOGS_EXPORTER
OpenTelemetry logs exporter selector; honoured only as an opt-out, where none turns telemetry export off. Every other value is not honoured.
- Audience: foreign
- Value:
string
OTEL_RESOURCE_ATTRIBUTES
OpenTelemetry resource attributes, percent-decoded key=value pairs; honoured, below [telemetry] resource_attributes. A malformed pair is skipped.
- Audience: foreign
- Value:
string
OTEL_SDK_DISABLED
OpenTelemetry SDK kill switch; a truthy value is honoured as an opt-out and turns telemetry export off.
- Audience: foreign
- Value:
bool
OTEL_SERVICE_NAME
OpenTelemetry service name; honoured as the exported service.name, below [telemetry] service_name.
- Audience: foreign
- Value:
string
PATH
Executable search path.
- Audience: foreign
- Value:
path_list
RUST_LOG
Log filter of the tracing subscriber.
Fallback filter, read only when neither OCX_LOG_CONSOLE nor OCX_LOG_LEVEL is set.
- Audience: foreign
- Value:
string
SIGSTORE_ID_TOKEN
OIDC token for keyless signing, from any provider.
- Audience: foreign
- Value:
string
SOURCE_DATE_EPOCH
Fixed timestamp for reproducible builds, in seconds since the epoch.
- Audience: foreign
- Value:
integer
SSL_CERT_DIR
CA directory OpenSSL-style clients use.
- Audience: foreign
- Value:
path - See: Proxy and corporate CA
SSL_CERT_FILE
CA bundle OpenSSL-style clients use.
- Audience: foreign
- Value:
path - See: Proxy and corporate CA
TEMP
Temporary directory on Windows.
- Audience: foreign
- Value:
path
TMP
Temporary directory on Windows, alternate spelling.
- Audience: foreign
- Value:
path
TMPDIR
Temporary directory.
- Audience: foreign
- Value:
path
USERPROFILE
The user’s home directory on Windows.
- Audience: foreign
- Value:
path
XDG_CONFIG_HOME
XDG configuration directory.
- Audience: foreign
- Value:
path
XDG_DATA_HOME
XDG data directory.
ocx self setup writes the nushell autoload file under $XDG_DATA_HOME/nushell/vendor/autoload/,
else under ~/.local/share/nushell/vendor/autoload/.
- Audience: foreign
- Value:
path
__MISE_ORIG_PATH
PATH before mise’s activation changed it.
- Audience: foreign
- Value:
path_list
all_proxy
Proxy URL for every scheme, lower-case spelling.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
http_proxy
HTTP proxy URL, lower-case spelling.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
https_proxy
HTTPS proxy URL, lower-case spelling.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
no_proxy
Hosts reached without a proxy, lower-case spelling.
- Audience: foreign
- Value:
string - See: Proxy and corporate CA
Shell and terminal
The login shell, the terminal type and the directory zsh reads its startup files from.
SHELL
The user’s login shell.
- Audience: foreign
- Value:
path
TERM
The terminal type.
TERM=dumb turns colour off. NO_COLOR and CLICOLOR_FORCE rank above it.
- Audience: foreign
- Value:
string
ZDOTDIR
Directory zsh reads its startup files from.
ocx self setup writes the zsh activation blocks into $ZDOTDIR instead of $HOME.
- Audience: foreign
- Value:
path
User name
The account name, which execution records store as a readable label.
LOGNAME
POSIX login name.
- Audience: foreign
- Value:
string
USER
POSIX user name.
- Audience: foreign
- Value:
string
USERNAME
Windows user name.
- Audience: foreign
- Value:
string
Windows system directories
Directories Windows sets, which OCX reads to refuse a system location for toolchain_dir.
APPDATA
Windows roaming application data directory.
- Audience: foreign
- Value:
path
ProgramData
Windows program data directory.
- Audience: foreign
- Value:
path
ProgramFiles
Windows program files directory.
- Audience: foreign
- Value:
path
ProgramFiles(x86)
Windows 32-bit program files directory.
- Audience: foreign
- Value:
path
SYSTEMROOT
Windows system root, upper-case spelling.
- Audience: foreign
- Value:
path
SystemRoot
Windows system root.
- Audience: foreign
- Value:
path