zotctl

zotctl is a small Bash CLI for local development workflows that need a disposable Zot registry with Podman.

It is intended for testing and development tasks such as:

• pushing locally built images during integration tests
• validating image publication flows
• standing up a temporary local OCI registry for ad hoc development

It intentionally owns only local registry lifecycle:

• up <port>
• down <port>
• version

It does not manage podman push logic, registry detection, or project-specific workflows.

Requirements

• podman
• curl
• make for install helpers

Usage

./zotctl up 5000
curl http://localhost:5000/v2/
./zotctl down 5000
./zotctl version

State is stored per port under:

${XDG_RUNTIME_DIR:-/tmp}/zotctl/<port>/

up is idempotent if the same managed container already exists. down is idempotent if it does not.

Install

Install globally:

make install
zotctl version

Override the install prefix if needed:

make install PREFIX="$HOME/.local"

Remove it later with:

make uninstall

For local verification, this repo may also use .tmp/ as scratch space for temporary install paths or other non-committed development artifacts.

Portable Bootstrap

Consumer repos can prefer a globally installed zotctl and fall back to a repo-local copy.

Pinned bootstrap example for v0.1.0:

# --- zotctl bootstrap ---
ZOTCTL_BIN="${ZOTCTL_BIN:-.zotctl}"
ZOTCTL_VERSION="${ZOTCTL_VERSION:-v0.1.0}"
ZOTCTL_URL="https://raw.githubusercontent.com/YOUR_ORG/zotctl/${ZOTCTL_VERSION}/zotctl"
if ! command -v zotctl >/dev/null 2>&1 && [[ ! -x "$ZOTCTL_BIN" ]]; then
 echo "Bootstrapping zotctl ${ZOTCTL_VERSION}..."
 curl -fsSL "$ZOTCTL_URL" -o "$ZOTCTL_BIN"
 chmod +x "$ZOTCTL_BIN"
fi
ZOTCTL="$(command -v zotctl || printf '%s' "$ZOTCTL_BIN")"
# --- end bootstrap ---

Usage:

$ZOTCTL up 5000
podman push localhost:5000/myimage:test

Cleanup Pattern

PORT=5000
cleanup() {
 "$ZOTCTL" down "$PORT" || true
}
trap cleanup EXIT
"$ZOTCTL" up "$PORT"
podman push localhost:$PORT/myimage:test

Notes

Current defaults are intentionally minimal:

• image: ghcr.io/project-zot/zot-linux-amd64:latest
• fixed internal Zot port: 5000
• generated config stored next to per-port data

If this grows later, the next likely additions are checksum-verified bootstrap, pinned release assets, configurable wait timeout, and logs support.