Inspect and verify a bundle in Next mode

Use bundle inspect for metadata and bundle verify for bundle signatures. Both commands accept local .tar.zst files and OCI references, not source directories or standalone bundle.uds.hcl files.

What you’ll accomplish

Inspect bundle metadata.
Verify a signature with a public key or keyless constraints.
Emit JSON or YAML for automation.

Prerequisites

UDS CLI installed
A local .tar.zst bundle artifact or an OCI bundle reference
A matching bundle public key or keyless certificate constraints for a signed artifact
jq installed for the JSON pipeline example

Steps

Inspect an artifact
Terminal window
```
# Local artifact
CLI_FEATURES=NextMode=true uds bundle inspect ./uds-bundle-my-app-amd64-1.0.0.tar.zst

# OCI artifact
CLI_FEATURES=NextMode=true uds bundle inspect oci://registry.example.com/my-org/my-app:1.0.0
```
Inspect displays bundle metadata, package sources, and dependencies. Its package status reflects checks from bundle creation. Without a verification policy, inspect does not verify the bundle signature. When you provide a public key, keyless constraints, or a configured policy, it verifies the bundle before displaying metadata.

Verify a signature

Verify with a public key:

CLI_FEATURES=NextMode=true uds bundle verify \
  ./uds-bundle-my-app-amd64-1.0.0.tar.zst \
  --public-key ./cosign.pub

Verify a keyless signature with certificate constraints:

CLI_FEATURES=NextMode=true uds bundle verify \
  ./uds-bundle-my-app-amd64-1.0.0.tar.zst \
  --certificate-identity-regexp 'https://github\.com/my-org/.*/\.github/workflows/release\.yml@refs/heads/main' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

The policy must identify the signer you trust. Package verification during creation does not prove bundle integrity.

Use structured output

create, inspect, pull, and reconfigure support text, json, and yaml output:

CLI_FEATURES=NextMode=true uds bundle inspect ./my-bundle.tar.zst -o json | jq '.packages[].name'
CLI_FEATURES=NextMode=true uds bundle inspect ./my-bundle.tar.zst -o yaml

Logs go to stderr. Structured output goes to stdout. Redirect stderr when a pipeline needs only JSON or YAML:

CLI_FEATURES=NextMode=true uds bundle inspect ./my-bundle.tar.zst -o json 2>/dev/null

Verification

Treat inspection and signature verification as separate checks. A successful bundle verify confirms the bundle signature under the supplied policy. It does not verify package signatures again.

Troubleshooting

Problem: Verification fails for a signed artifact

Symptom: bundle verify cannot validate the signature.

Solution: Confirm that the key or keyless constraints match the signer. Confirm that the artifact was not changed after signing.

Create a bundle in Next mode - Create a bundle artifact to inspect.
Deploy a bundle in Next mode - Deploy verified artifacts.
Next mode reference - Review the bundle format and supported commands.