# ocx_sdk

*module*

Python SDK for [OCX](https://github.com/ocx-sh/ocx).

`ocx-sdk` drives the ocx binary rather than reimplementing it: ocx owns
resolution, verification, and the identifier grammar, and this package gives
you typed, CWD-independent handles over the commands it exposes.

```python
from ocx_sdk import Ocx, bootstrap

ocx = Ocx(exe=bootstrap.ensure())
project = ocx.project("/srv/build")
project.pull()
project.exec(["task", "verify"])
```

**This module is the API.** Everything listed in `__all__` is the stable
surface; every other module is underscored and package-private, and the one
public submodule is `ocx_sdk.bootstrap`. Reaching into an underscored path
means the next release may move it without notice — pre-1.0, breaking
changes ship without shims.

Start at `Ocx` for the runtime API and `bootstrap.ensure` for provisioning.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/__init__.py#L1-L1)

## ocx_sdk.ConfigCommands

*class* · *dataclass*

```python
class ConfigCommands
```

Re-exported from: `ocx_sdk._client`

The `ocx config` command group — the corporate managed-config tier.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L3370-L3457)

### ocx_sdk.ConfigCommands.setup

*method*

```python
def setup(managed_config: str | None = None, dry_run: bool = False, force: bool = False, timeout: MaybeTimeout = UNSET, retry: MaybeRetry = UNSET) -> ConfigSetupReport
```

Adopt, or clear, the managed-config tier.

Installs no binary and touches no shell profile — the
automation-shaped counterpart to `self setup --managed-config`.

**Parameters**

- `managed_config` (`str | None`) (default: `None`) — An OCI reference to a managed-config artifact. `MANAGED_CONFIG_DISABLED` clears an existing seed. `None` falls back to the ambient source, then the existing seed.
- `dry_run` (`bool`) (default: `False`) — Report the intended actions without writing.
- `force` (`bool`) (default: `False`) — Overwrite a managed fence that carries local edits.
- `timeout` (`MaybeTimeout`) (default: `UNSET`) — Seconds per attempt. Omitted takes the config's.
- `retry` (`MaybeRetry`) (default: `UNSET`) — Retry policy. `None` opts out; omitted takes the config's.

**Returns**

- (`ConfigSetupReport`) — The status ocx recorded.

**Raises**

- `DirtyRcBlockError` — The fence carries local edits and `force` is
unset.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L3379-L3417)

### ocx_sdk.ConfigCommands.update

*method*

```python
def update(version: str | None = None, *, check_only: bool = False, pause: str | None = None, resume: bool = False, timeout: MaybeTimeout = UNSET, retry: MaybeRetry = UNSET) -> ConfigUpdateReport
```

Refresh the managed-config snapshot from the registry.

Unlike the project-tier `lock --check`, this command answers `--check`
with a full payload — `status` reads `checked` or `check_unavailable`.

**Parameters**

- `version` (`str | None`) (default: `None`) — A tag, `sha256:<hex>`, or `tag@sha256:<hex>` to sync. `None` follows the seed's own source.
- `check_only` (`bool`) (default: `False`) — Report status — drift, pause, pin — without fetching or swapping. ocx's `--check`.
- `pause` (`str | None`) (default: `None`) — Hold the background refresh for a duration such as `4h` or `3d`, up to seven days.
- `resume` (`bool`) (default: `False`) — Clear an active pause and refresh immediately.
- `timeout` (`MaybeTimeout`) (default: `UNSET`) — Seconds per attempt. Omitted takes the config's.
- `retry` (`MaybeRetry`) (default: `UNSET`) — Retry policy. `None` opts out; omitted takes the config's.

**Returns**

- (`ConfigUpdateReport`) — The tier's status, source, digest, and policy.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L3419-L3457)

## ocx_sdk.PatchCommands

*class* · *dataclass*

```python
class PatchCommands
```

Re-exported from: `ocx_sdk._client`

The `ocx patch` command group.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L3460-L3491)

### ocx_sdk.PatchCommands.sync

*method*

```python
def sync(platform: str | None = None, timeout: MaybeTimeout = UNSET, retry: MaybeRetry = UNSET) -> CommandResult
```

Refresh patch descriptors and companion packages.

Re-checks every installed package, including ones installed before
patches were configured, and needs network access. Returns the raw
result: no payload shape is pinned for this command yet.

**Parameters**

- `platform` (`str | None`) (default: `None`) — The platform to resolve against.
- `timeout` (`MaybeTimeout`) (default: `UNSET`) — Seconds per attempt. Omitted takes the config's.
- `retry` (`MaybeRetry`) (default: `UNSET`) — Retry policy. `None` opts out; omitted takes the config's.

**Returns**

- (`CommandResult`) — The exit code and whatever ocx printed.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L3469-L3491)