Explore OCI container images without running them.
cek is a command-line utility for filesystem exploration inside OCI container images. It focuses on browsing files, reading contents, and inspecting layer mechanics—without running containers. cek reads images directly from local container daemons (Docker, Podman, containerd, etc.) or pulls them from remote registries.
cek runs without root privileges and works with any OCI-compliant image registry. While it does not require a container daemon, it can leverage one when available to access locally cached images and avoid registry rate limits. Most importantly, cek never runs containers.
go install github.com/bschaatsbergen/cek@latestOr build from source:
git clone https://github.com/bschaatsbergen/cek.git
cd cek
go build -o cek .View image details including digest, creation time, architecture, total size, and individual layer information.
cek inspect nginx
Image: nginx
Registry: index.docker.io
Digest: sha256:ec0ee8695f2f71addca9b40f27df0fdfbde460485a2b68b834e18ea856542f1e
Created: 2025-12-09T22:50:18Z
OS/Arch: linux/arm64
Size: 55.6 MB
Layers:
# Digest Size
1 sha256:f626fba1463b32b20f78d29b52dcf15be927dbb5372a9ba6a5f97aad47ae220b 28.7 MB
2 sha256:89d0a1112522e6e01ed53f0b339cb1a121ea7e19cfebdb325763bf5045ba7a47 26.8 MB
3 sha256:1b7c70849006971147c73371c868b789998c7220ba42e777d2d7e5894ac26e54 627 B
4 sha256:b8b0307e95c93307d99d02d3bdc61c3ed0b8d26685bb9bafc6c62d4170a2363e 954 B
5 sha256:fe1d23b41cb3b150a19a697809a56f455f1dac2bf8b60c8a1d0427965126aaf9 403 B
6 sha256:fda1d961e2b70f435ee701baaa260a569d7ea2eacd9f6dba8ac0320dc9b7d9fe 1.2 KB
7 sha256:10dbff0ec650f05c6cdcb80c2e7cc93db11c265b775a7a54e1dd48e4cbcebbbc 1.4 KBBy default, cek ls shows the merged overlay filesystem, which is what you see
inside a running container. All layers are combined, with upper layers
overriding lower ones.
You can optionally specify a path to list only files under a specific directory.
# Show all files (merged overlay view)
cek ls nginx:latest
# List files in a specific directory
cek ls nginx:latest /etc
cek ls nginx:latest /etc/nginx
# Combine path with pattern filter
cek ls nginx:latest /etc/nginx --filter '*.conf'
# Filter by pattern (supports doublestar glob matching)
cek ls --filter '**/nginx/*.conf' nginx:latest
# Show files from a specific layer only
cek ls --layer 1 nginx:latestPatterns without slashes match against basenames. Patterns with slashes match
against full paths. Use ** for recursive directory matching.
Write file contents to standard output from any image without creating a container. Output can be piped to other commands or redirected to files for inspection, diffing, or processing.
cek cat nginx:latest /etc/nginx/nginx.conf
# Read from a specific layer
cek cat --layer 2 nginx:latest /etc/os-release
# Pipe to other tools
cek cat alpine:latest /etc/os-release | grep VERSION_ID
# Compare configuration between image versions
diff <(cek cat nginx:1.25 /etc/nginx/nginx.conf) \
<(cek cat nginx:1.24 /etc/nginx/nginx.conf)The cat command searches layers top-down to find the final file state after
all overlays, just like in a running container.
Compare images from the same repository to see what changed between versions. Only files from unique layers are analyzed, making comparisons fast even for large images with shared base layers.
cek compare alpine:3.19 alpine:3.18The comparison skips shared base layers automatically, reducing I/O for images with common ancestry.
List all tags in a repository from the remote registry, allowing you to find available tags or a specific tag.
cek tags nginx
# Limit output to first N tags
cek tags alpine --limit 20
# Pipe to less for pagination
cek tags nginx | less
# Filter tags with grep
cek tags nginx | grep '^1\.2'
cek tags python | grep -E '^3\.(11|12)'Note: This queries the remote registry directly, not the local daemon cache.
Export OCI images to tar files, including manifest, config, and all layers. These tarballs make it easy to move images between environments, share images without a registry, or back them up for disaster recovery.
# Export an image to a tar file
cek export alpine:latest -o alpine.tar
# Export a specific platform
cek export --platform linux/amd64 ubuntu:22.04 -o ubuntu-amd64.tar
# Load the exported tar into Docker or Podman
docker load -i alpine.tar
podman load -i alpine.tarUse cases include air-gapped deployments, image backups, sharing images without pushing to a registry, and transferring images between different container runtimes.
Show the directory tree structure of an OCI image, making it easy to visualize the filesystem layout.
# Show the top-level directories in an image
cek tree nginx:latest -L 1
# Inspect the /usr/local/bin folder of a specific layer
cek tree --layer 4 python:3.12-slim /usr/local/bincek works with all popular container daemons by connecting to the container daemon socket. The daemon provides access to locally cached images, avoiding rate limits when exploring images you've already pulled.
Set DOCKER_HOST to point to your runtime's socket:
# Docker (standard Linux)
export DOCKER_HOST=unix:///var/run/docker.sock
# Docker Desktop (macOS)
export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock
# Colima (macOS)
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
# Podman (Linux with XDG_RUNTIME_DIR)
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
# Podman Machine (macOS)
export DOCKER_HOST=unix://$HOME/.local/share/containers/podman/machine/podman.sockIf DOCKER_HOST is not set, cek will attempt to use the default Docker socket
location.
cek defaults to if-not-present to avoid registry rate limits. Images are
fetched from your local container daemon cache when available, falling back to
the remote registry only if needed.
# Use local cache if available, pull if missing (default)
cek inspect --pull if-not-present nginx:latest
# Always pull from registry, even if cached locally
# Useful for checking if :latest tag has been updated
cek inspect --pull always nginx:latest
# Only use local cache, never pull from registry
# Useful for offline work or avoiding network calls
cek inspect --pull never nginx:latestImages pulled by docker pull, nerdctl pull or podman pull are immediately
available to cek without additional downloads.
When using if-not-present, cek checks the local container daemon first. If the
image exists locally, it's used immediately without any network calls. If not
found locally, cek pulls from the remote registry.