CLI reference

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

Installed help output

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

Set defaults in your shell

export OCI_BAI_SERVER=http://localhost:50051
export OCI_BAI_REPO=my-repo

Example output

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

bash

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

output

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

bash

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

output

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

bash

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

output

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

bash

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

output

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

oci-bai log <ref>

Commit history for a ref.

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

Compare two versions.

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

output

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

oci-bai search <query>

Search the catalog. See the Search guide for the full syntax.

output

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

oci-bai provenance <ref>

Full derivation tree for a version.

output

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

oci-bai whodepends <ref>

Every version that descends from this one.

oci-bai checkout <ref> [--paths] [--dest]

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)

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.

output

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

Push layers first

Push each member's image through the gateway before running cohort push.

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

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

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

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

oci-bai fsck <ref>

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

← Provenance