Skip to content

Quickstart

Install

uv add ocx-sdk

or, with pip:

pip install ocx-sdk

Requires Python 3.12+. Zero runtime dependencies — the wheel pulls in nothing but itself.

The canonical CI journey

Bootstrap a pinned ocx binary, resolve a project, pull its declared toolchain, run inside it. This is the shape almost every consumer of this SDK ends up writing:

# illustrative: /srv/build stands in for a real project directory (one
# holding ocx.toml), and bootstrap.ensure() needs network access — swap in
# your own path to run this for real.
from ocx_sdk import Ocx, bootstrap

ocx = Ocx(exe=bootstrap.ensure())
project = ocx.project("/srv/build")
project.pull()
result = project.exec(["task", "verify"])
print(result.exit_code, result.stdout)
  • bootstrap.ensure() downloads, verifies, and caches a pinned ocx binary, then returns its path. It is idempotent — a cache hit that still hashes correctly needs no network at all. See Bootstrap for pinning and mirrors.
  • Ocx(exe=...) resolves the binary once and pins it to the handle for its lifetime; the handle is frozen and thread-safe.
  • ocx.project(path) returns a Project whose every call carries --project <path> explicitly, so nothing depends on the working directory. See Projects & toolchains.
  • project.pull() materializes everything ocx.lock declares — the "install" step of the journey.
  • project.exec([...]) runs a command inside the project's composed environment and hands back its exit code and output.

If a pinned binary is already on PATH or named by OCX_SDK_EXE — the shape a CI image typically arranges — the simplest possible live check needs no project at all:

from ocx_sdk import Ocx

ocx = Ocx()
print(ocx.version())

Two things to unlearn from the CLI

There is no ocx.exec

Raw argv — anything the SDK doesn't type — goes through ocx.invoke(argv) (or invoke_async/spawn/spawn_async). The toolchain runner that mirrors ocx exec on the CLI is project-tier: ocx.project(path).exec(argv). Reaching for ocx.exec — or ocx.run, the name that verb carried before ocx 0.6 — raises AttributeError with a pointer to the right method; the SDK reserves both names on purpose.

Package-tier commands are machine tier

ocx.package — install, select, exec, and the author flow (create/test/push) — operates on $OCX_HOME directly and takes no project path. It is a sibling of ocx.project(...), not something reached through it.

Where to go next