Command ↔ method map¶
Every typed method mirrors one ocx command. T1 commands are typed and
CI-covered; T2 commands are real but not yet typed (reach them through
invoke or invoke_async);
T3 commands are interactive, shell-session, or not-a-frozen-contract, and
stay invoke-only by design; ✗ commands are never wrapped.
Full flag fidelity is scoped to stable, resolution-affecting flags —
experimental surfaces (--ci=gitlab and similar) are excluded on purpose.
Machine tier — Ocx¶
No project path; operates on $OCX_HOME.
| ocx command | SDK method | Tier |
|---|---|---|
ocx version |
Ocx.version |
T1 |
ocx about |
Ocx.about |
T1 |
ocx login |
Ocx.login |
T1 |
ocx logout |
Ocx.logout |
T1 |
ocx status |
Ocx.project(path).status |
T1 |
ocx clean |
Ocx.clean |
T1 |
| any command | Ocx.invoke / invoke_async / spawn / spawn_async |
raw escape hatch |
ci*, bare aliases |
— | ✗ dead stubs |
direnv* |
— | T3, needs human direnv allow |
shell allow / shell revoke / shell state |
— | T3, shell-session, needs human consent |
self activate, shell completion |
— | T3, shell-session only |
Project tier — Ocx.project(path)¶
Every call carries --project <path> explicitly, so no method reads the
working directory.
| ocx command | SDK method | Tier |
|---|---|---|
ocx init --project |
Project.init |
T1 |
ocx add --project |
Project.add |
T1 |
ocx remove --project |
Project.remove |
T1 |
ocx lock --project |
Project.lock |
T1 |
ocx update --project |
Project.update |
T1 |
ocx pull --project |
Project.pull |
T1 |
ocx status --project |
Project.status |
T1 |
ocx inspect --project |
Project.inspect |
T1 |
ocx env --project |
Project.env |
T1 |
ocx exec --project -- CMD |
Project.exec / exec_async / spawn / spawn_async |
T1 |
Package tier — Ocx.package¶
Consumer surface: installing and running packages from $OCX_HOME, no
project path.
| ocx command | SDK method | Tier |
|---|---|---|
ocx package install |
package.install |
T1 |
ocx package select |
package.select |
T1 |
ocx package uninstall |
package.uninstall |
T1 |
ocx package deselect |
package.deselect |
T1 |
ocx package env |
package.env |
T1 |
ocx package exec |
package.exec / exec_async / spawn / spawn_async |
T1 |
ocx package which |
package.which † |
T1 |
ocx package inspect |
package.inspect |
T1 |
ocx package description pull |
package.description_pull |
T1 |
ocx package deps |
package.deps |
T1 |
ocx package pull |
package.pull |
T1 |
ocx package create |
package.create |
T1, author flow |
ocx package receipt |
package.receipt |
T1, author flow — 79 (no receipt) reads as None |
ocx package test --script |
package.test |
T1, author flow — stable v1 JSON, report-then-fail ‡ |
ocx package test -- CMD |
Ocx.invoke |
prints the child's raw stdout even under --format json; never parsed here |
ocx package push |
package.push |
T1, author flow |
ocx package description push |
package.description_push |
T1, author flow |
ocx package sign |
package.sign |
T1, author flow |
ocx package verify |
package.verify |
T1 |
ocx package attest |
package.attest |
T1, author flow |
ocx package sbom |
package.sbom |
T1 |
ocx package copy |
package.copy |
T1, author flow |
ocx package announce |
package.announce |
T1, author flow — --yank, --unyank, --fork, --out stay invoke-only |
ocx package claim |
package.claim |
T1, author flow |
ocx package cascade check |
package.cascade_check |
T1, report-then-fail ‡ |
ocx package cascade repair |
package.cascade_repair |
T1, author flow — report-then-fail ‡ |
† package which's JSON is doc-flagged "breaking, pre-1.0" — typed, but not
on ocx's durable-anchor list. EnvReport's four non-entry arrays carry the
same flag.
‡ Report-then-fail: ocx prints the report and exits non-zero when it has
a finding (package test exits 1 on a failed assertion, cascade * exits
65 on a stale or missing tag). The SDK tolerates that exit and hands the
report back as a result — TestResult.passed, CascadeCheckReport.clean
— because the finding is the answer. Only a non-zero exit with no report
(an error envelope
or nothing parseable) raises. Guard: tolerated_report.
Config tier — Ocx.config¶
The corporate managed-config surface.
| ocx command | SDK method | Tier |
|---|---|---|
ocx config setup |
config.setup |
T1 |
ocx config update |
config.update |
T1 |
ocx config test, ocx config push |
— | T2 |
Index tier¶
| ocx command | SDK method | Tier |
|---|---|---|
ocx index update/catalog/list/sync/regenerate |
— | T2, whole group |
Patch tier — Ocx.patch¶
| ocx command | SDK method | Tier |
|---|---|---|
ocx patch sync |
patch.sync |
T1 |
ocx patch publish/test/freeze/why |
— | T2 |
Self tier¶
| ocx command | SDK method | Tier |
|---|---|---|
ocx self setup, ocx self update |
— | T2 |
ocx self activate |
— | T3, shell-session |
The SDK never calls self setup, self activate, or anything else that
mutates the machine outside $OCX_HOME — see
bootstrap for what ensure() does instead.
Provisioning — not an ocx command¶
bootstrap.ensure is a Python-only layer
above the CLI: it resolves, downloads, verifies, and caches an ocx binary,
then returns its path. See bootstrap.