oci-bai CLI Reference

Every oci-bai command and its flags. Run oci-bai <command> --help for the installed version.

Installed help output

Execution-native, OCI-compatible artifact-graph CLI (§14)

Usage: oci-bai [OPTIONS] <COMMAND>

Commands:
  init          Initialize an image repo
  push          Push, CDC, commit, tag
  log           Commit DAG for this family
  op            Operation-log commands
  branch        List image families with divergent heads
  bookmark      Bookmark commands
  undo          Invert the last op-log entry
  fsck          Graph + chunk-store integrity
  gc            Mark-and-sweep GC
  diff          Diff two refs at a depth
  search        Search the catalog
  mount         Lazy-snapshotter mount plan
  show          Manifest + SBOM + provenance + size by depth
  explain       Derivation + composition + provenance + drift
  resolve       Path provenance
  provenance    Full derivation tree
  whodepends    Reverse derivation walk
  referrers     List referrers of a subject manifest
  lineage       Lineage commands
  compose       Environment assembly on the graph plane
  checkout      Sparse checkout
  cohort        Transactional N-image cohort push
  optimize      Emit Rationale records
  attach-bench  Attach a benchmark verdict
  hunt          Host a verdictml HuntEnv episode
  help          Print this message or the help of the given subcommand(s)

Options:
      --server <SERVER>  oci-jj-server gRPC endpoint
      --repo <REPO>      Repository (image family) the command targets
  -h, --help             Print help
  -V, --version          Print version

Global flags

Flag	Description
`--server URL`	Server endpoint (default `http://127.0.0.1:50051`)
`--repo NAME`	Repository to target
`--help / -h`	Show help
`--version / -V`	Print version

Example output

These examples use a small demo family named rl-gym-env.

oci-bai --repo rl-gym-env log cartpole

commit ab7c49d0e6f3  cartpole
parent f84a2d7e91b0  cuda-base
manifest sha256:2ef7a63bbd4c70f58fc4e7b42d228a42f0ca9288e3fa4b6f9ab173079a8f284d
builder trainer@briefcase
message cartpole policy image with safetensors checkpoint

oci-bai search "format==safetensors cuda>=12.4"

rank  repo        ref       format       manifest
1     rl-gym-env  acrobot   safetensors  sha256:dd21ce69ba84...
2     rl-gym-env  cartpole  safetensors  sha256:2ef7a63bbd4c...

oci-bai --repo rl-gym-env provenance acrobot

acrobot
  derives from cartpole
cartpole
  derives from cuda-base
cuda-base
  shared CUDA 12.4 runtime base

oci-bai --repo rl-gym-env diff cuda-base cartpole --depth package

@@ packages
+ gymnasium 1.1.0
+ numpy 1.26.4
~ torch 2.3.1 -> 2.4.0

log

oci-bai log <ref>

Commit history for a ref.

diff

oci-bai diff <from> <to> [--depth <depth>]

Compare two versions.

`--depth` value	What it shows
`bytes`	Byte-level diff
`file`	File-level diff (default)
`package`	Package changes
`semantic`	Config changes (entrypoint, CUDA, OS)
`imports`	Runtime imports when telemetry is available
`loaded-libs`	Loaded shared libraries when telemetry is available
`syscalls`	Syscall changes when telemetry is available
`bench`	Benchmark verdict deltas when attached

Usage: oci-bai diff [OPTIONS] <FROM> <TO>

Options:
      --depth <DEPTH>    [default: file]
                         [possible values: bytes, file, package, semantic, imports, loaded-libs, syscalls, bench]
      --server <SERVER>  oci-jj-server gRPC endpoint
      --repo <REPO>      Repository (image family) the command targets
  -h, --help             Print help

search

oci-bai search <query>

Search the catalog. See the Search guide at oci.briefcaseai.io for the full syntax.

Usage: oci-bai search [OPTIONS] <QUERY>

Options:
      --semantic
      --server <SERVER>  oci-jj-server gRPC endpoint
      --repo <REPO>      Repository (image family) the command targets
  -h, --help             Print help

Built-in facets: cuda, python, os, arch, format, model. Any name not in this list is treated as a package name.

oci-bai search "cuda>=12.4 format==safetensors arch==arm64"
oci-bai search "gymnasium==1.1.0"
oci-bai search "model==true"

provenance

oci-bai provenance <ref>

Full derivation tree for a version.

Usage: oci-bai provenance [OPTIONS] <REFERENCE>

Options:
      --server <SERVER>  oci-jj-server gRPC endpoint
      --repo <REPO>      Repository (image family) the command targets
  -h, --help             Print help

whodepends

oci-bai whodepends <ref>

Every version that descends from this one.

checkout

oci-bai checkout <ref> [--paths <a,b>] [--dest <dir>]

Fetch specific files without pulling the full image.

Flag	Description
`--paths a,b`	Comma-separated path prefixes to fetch
`--dest dir`	Materialize files here (requires server-side staging)

cohort push

oci-bai cohort push <dir>

Push multiple related images atomically. Shared content is uploaded once regardless of how many members reference it. Reads cohort.json from the directory.

Usage: oci-bai cohort push [OPTIONS] <DIR>

Options:
      --server <SERVER>  oci-jj-server gRPC endpoint
      --repo <REPO>      Repository (image family) the command targets
  -h, --help             Print help

undo

oci-bai undo [--op <id>]

Revert the last push, or a specific operation. History is append-only — undo is non-destructive.

referrers

oci-bai referrers <sha256:digest> [--mine]

List referrers of an image. --mine shows your own private referrers.

fsck

oci-bai fsck <ref>

Verify that every file in a version can be fully reconstructed from stored data.