CLI

If you want to resolve or inspect an image from a shell, script, or CI job, the CLI gives you that path without requiring application code. It provides resolve, validate, and inspect over the same public resolver used by the library.

Quick start

Build the executable, then put command options before the image argument:

zig build

./zig-out/bin/z-oci resolve --platform linux/amd64 ubuntu:22.04
./zig-out/bin/z-oci validate ubuntu@sha256:<64-hex-digest>
./zig-out/bin/z-oci inspect --format json ubuntu:22.04

Registry commands may contact a live HTTPS registry. Credentials are configured through the process adapter; they are not command-line arguments. See Credentials for the supported process sources.

z-oci --version prints z-oci 0.7.0. Use z-oci --help or z-oci <command> --help for the complete option text.

Commands and options

The top-level form is:

z-oci [global-options] <command> [command-options] <image>

Commands:

• resolve <image> resolves an image reference to a verified digest-pinned reference.
• validate <image@sha256:...> checks whether an exact sha256 digest exists in the registry.
• inspect <image> shows the top-level manifest or index and optional selected-leaf metadata.

Options that configure the process adapter must come before the command:

• --ca-bundle <path> uses a public CA bundle for registry HTTPS.
• --helper-timeout-ms <ms> sets the credential-helper I/O timeout.

--help and --version can be used at the top level or as the sole option after a command.

Command options must come after the command and before the image:

• --format text|json selects the output format. The default is text.
• --platform <os/arch[/variant]> selects a platform for multi-arch images. It is available for resolve and inspect.
• --verbose writes elapsed time and the outcome to standard error.

The library Config fields for retries, response limits, token-cache capacity, and connect timeout are not CLI options. The CLI exposes the process-facing CA-bundle and credential-helper timeout settings listed above.

Output

Text output is compact and suitable for terminal use or shell pipelines. JSON output is command-specific and intended for programmatic consumers.

Successful resolve output contains a pinned reference in text mode:

registry-1.docker.io/library/ubuntu@sha256:<64-hex-digest>

In JSON mode, resolve returns the input, pinned reference, digest, media type, and selected platform:

{"command":"resolve","input":"ubuntu:22.04","reference":"registry-1.docker.io/library/ubuntu@sha256:<64-hex-digest>","digest":"sha256:<64-hex-digest>","media_type":"application/vnd.oci.image.manifest.v1+json","platform":{"os":"linux","architecture":"amd64","variant":null,"os_version":null,"os_features":null}}

validate reports its result in text mode:

validate success: valid
validate not found: not-found

Its JSON form contains the reference and a boolean result:

{"command":"validate","reference":"registry-1.docker.io/library/ubuntu@sha256:<64-hex-digest>","valid":true}

inspect text lists top-level metadata and, when requested, the selected leaf. A single-manifest result looks like this:

inspect:
  reference: registry-1.docker.io/library/ubuntu:22.04
  top_level.kind: manifest
  top_level.media_type: application/vnd.oci.image.manifest.v1+json
  top_level.config_digest: sha256:<64-hex-digest>
  top_level.layers.count: 0

inspect --format json returns command, reference, top_level, and selected_leaf. top_level contains the manifest or index kind, media type, config digest, and layer count; for an index, it also contains platform descriptors. selected_leaf is an object containing the requested platform and selected manifest metadata, or null when no leaf was selected. For an index, use --platform os/arch[/variant] when you need a selected leaf.

Streams and failures

Successful results, help, and version output go to standard output. Text failures and verbose timing go to standard error. JSON failures remain on standard output so callers can parse the error object.

A verbose line has this form, with the measured value varying by run:

z-oci verbose: command=resolve outcome=success elapsed_ms=37

Numeric exit codes are:

0   success
1   not found
2   authentication failure
3   rate limited
4   network failure
5   usage failure
6   local configuration failure
7   digest failure
8   content type failure
9   manifest content failure
10  timeout
11  platform selection failure
12  unexpected failure

Diagnostics do not include credentials, authorization values, credential-helper data, raw headers, or response bodies.

For credential setup and trust-bundle behavior, see Credentials. For platform matching and configured limits, see Platform and limits. Troubleshooting covers common command and registry failures.