CLI Only Quickstart

CLI-only quickstart

This procedure requires no project configuration file, manifest editing, Dockerfile, or manual JSON manipulation. It starts from an already compiled Linux executable.

1. Install or activate the commands

Linux or macOS:

scripts/local/bootstrap.sh
source .platform-factory/activate

Windows PowerShell:

.\scripts\local\bootstrap.ps1
. .\.platform-factory.ps1

Check the active command:

secure-oci version
secure-oci help

2. Build and verify one platform

secure-oci build \
  --platform linux/amd64 \
  --image ghcr.io/OWNER/APP --tag v1 \
  --output ./app-layout \
  ./app-linux-amd64

secure-oci verify ./app-layout

No config file is required. Runtime options can be passed directly:

secure-oci build \
  --platform linux/amd64 \
  --image ghcr.io/OWNER/APP --tag v1 \
  --entrypoint /app/service \
  --profile static \
  --label org.opencontainers.image.description="My service" \
  --compression fast \
  --output ./app-layout \
  ./app-linux-amd64

3. Build AMD64 and ARM64 together

secure-oci build \
  --image ghcr.io/OWNER/APP --tag v1 \
  --platform linux/amd64=./app-linux-amd64 \
  --platform linux/arm64=./app-linux-arm64 \
  --output ./app-multi

secure-oci inspect ./app-multi
secure-oci verify ./app-multi

Each executable is independently packaged and verified. The CLI creates the multi-platform index atomically.

4. Publish, sign, and capture the immutable reference

Preview without changing the registry:

secure-oci publish --dry-run --sign --sbom \
  ./app-multi ghcr.io/OWNER/APP:v1

Publish and capture the digest-pinned reference without jq or manual JSON:

IMAGE_REF=$(secure-oci publish \
  --yes --sign --sbom --format reference \
  ./app-multi ghcr.io/OWNER/APP:v1)

printf '%s\n' "$IMAGE_REF"

PowerShell:

$ImageRef = secure-oci publish `
  --yes --sign --sbom --format reference --provenance provenance.json `
  --policy policy.json --evidence evidence.json `
  .\app-multi ghcr.io/OWNER/APP:v1

publish verifies the layout, uploads it through the native Distribution client and signs the immutable image@sha256:... subject with the native Ed25519 engine. SBOM and provenance artifacts are generated or attached by the same binary; Skopeo, Syft and the Cosign CLI are not required by this path. Production publication additionally requires an explicit policy and its derived evidence.

5. Run locally

Run the local layout directly. The CLI verifies and imports it into Podman only when the image is absent:

secure-oci run \
  --runtime podman \
  --network bridge \
  -p 127.0.0.1:8080:8080 \
  ./app-multi

No tar, podman load, or temporary image archive is needed.

Container:

secure-oci run \
  --isolation container \
  --runtime podman \
  --network bridge \
  -p 127.0.0.1:8080:8080/tcp \
  -p 127.0.0.1:8443:8443/tcp \
  "$IMAGE_REF"

Replace podman with docker if desired.

Native microVM on a prepared Linux/KVM host:

secure-oci run \
  --isolation microvm \
  --layout ./app-layout \
  -p 127.0.0.1:8080:8080/tcp \
  --port 127.0.0.1:5353:53/udp

-p, --port, and --publish are equivalent and repeatable. Values use PORT, HOST:GUEST, or IP:HOST:GUEST, with optional /tcp or /udp.

6. Deploy and rollback

Preview the generated restricted Deployment:

secure-oci deploy --dry-run \
  --name app --namespace production \
  "$IMAGE_REF"

Apply it and wait for the rollout:

secure-oci deploy \
  --name app --namespace production \
  "$IMAGE_REF"

Preview and perform rollback:

secure-oci rollback --dry-run --namespace production app
secure-oci rollback --yes --namespace production app

PowerShell uses $ImageRef instead of "$IMAGE_REF". Deployment requires kubectl access to the intended cluster and rejects mutable tags.

7. Leave the local environment

deactivate_secure_oci

PowerShell uses deactivate-secure-oci; CMD uses deactivate.bat.