wolfictl/README.md
Kyle Quest 99af1cae80 wolfictl apk extract-locked-configs CLI command
Signed-off-by: Kyle Quest <kcq.public@gmail.com>
2026-05-17 14:12:13 -07:00

14 KiB

wolfictl

Documentation Go Report Card

This is an enhanced version of the wolfictl CLI tool for working with Wolfi (the original repo is here: https://github.com/wolfi-dev/wolfictl ).

The Enhancements

This enhanced version adds two new sub-commands under wolfictl apk and extends an existing one. All operate on the standard wolfi APKINDEX format (https://packages.wolfi.dev/os/x86_64/APKINDEX.tar.gz by default) and on individual .apk files (local paths or http(s):// URLs).

New: wolfictl apk cpall — bulk-copy packages from an index

Like wolfictl apk cp, but copies all packages in the index (or a filtered subset) instead of requiring you to name each package on the command line. Supports pagination so you can pull a large repository in chunks, and a regex filter for selecting packages by name.

Flags:

Flag Default Description
-i, --index https://packages.wolfi.dev/os/x86_64/APKINDEX.tar.gz APKINDEX URL to read
-o, --out-dir ./packages Local directory to copy into (writes to <out-dir>/<arch>/)
--gcs (empty) Read packages from a GCS bucket instead of the HTTP repo (gs://bucket/path)
--latest false Copy only the latest version of each package
--limit 10 Max packages to copy after --offset (0 = no limit)
--offset 0 Skip this many packages from the start of the filtered, name-sorted set
--package-filter (empty) Only copy packages whose name matches this Go regex (unanchored — use ^...$ for exact match)

Examples:

# Default: copy the first 10 packages (alphabetical) into ./packages/x86_64/
wolfictl apk cpall

# Copy every "go-*" package, latest version of each, into ./mirror
wolfictl apk cpall --package-filter '^go-' --latest --limit 0 -o ./mirror

# Pagination: pull packages 100–199 of the filtered set
wolfictl apk cpall --package-filter '^lib' --offset 100 --limit 100

After copying, cpall rewrites a local APKINDEX.tar.gz in the output directory containing every .apk it finds there (across runs), so subsequent paginated runs accumulate into a usable local mirror.

Notable behavior:

  • Deterministic pagination. Packages are sorted by name (then version) before --offset/--limit are applied, so the same --offset N --limit M always produces the same slice.
  • Bounded concurrency. Downloads run in parallel with a cap of 16 in-flight requests.
  • Atomic writes. Each .apk is downloaded to <name>.part, then os.Rename-d into place — an interrupted run can't leave a half-written file that a future run would mistakenly skip.
  • HTTP status validated. A non-2xx response (404, 403, 5xx) is reported as an error rather than silently written into the .apk file.
  • Path-traversal guard. Package filenames that would escape the output directory are rejected (defense for users running against untrusted indexes).
  • Resilient index rewrite. Unparseable .apk files in the output directory are logged and skipped instead of aborting the local index rewrite.

New: wolfictl apk pi — list files inside an .apk package

This command accepts either a local file path or an http(s):// URL. Produces a tar -tv-style listing of every entry across the apk's signature/control/data streams.

# Local file
wolfictl apk pi ./packages/x86_64/ca-certificates-bundle-20251003-r0.apk

# HTTP URL (e.g. taken from `wolfictl apk ls --full`)
wolfictl apk pi https://packages.wolfi.dev/os/x86_64/ca-certificates-bundle-20251003-r0.apk

Output:

-rw-r--r-- 0/0        392 2025-11-10 10:47 .PKGINFO
-rw-r--r-- 0/0      26034 2025-11-10 10:47 .melange.yaml
drwxr-xr-x 0/0          0 2025-11-10 10:47 etc/ssl/certs
Lrwxrwxrwx 0/0          0 2025-11-10 10:47 etc/ssl/cert.pem -> certs/ca-certificates.crt
-rw-r--r-- 0/0     222204 2025-11-10 10:47 etc/ssl/certs/ca-certificates.crt

Enhanced: wolfictl apk ls --package-filter

The existing wolfictl apk ls command now accepts a --package-filter flag that takes a Go regex matched (unanchored) against package names. This composes with the existing exact-match --package/-P flag (intersection) and with --latest, --newer-than, --full, and --json.

# All "go-*" packages currently in the wolfi index
wolfictl apk ls https://packages.wolfi.dev/os/x86_64/APKINDEX.tar.gz --package-filter '^go-'

# Latest versions of anything matching "tls" or "ssl", as JSON
wolfictl apk ls https://packages.wolfi.dev/os/x86_64/APKINDEX.tar.gz \
  --package-filter '(tls|ssl)' --latest --json

New: wolfictl apk extract-locked-configs — turn a Chainguard locked_config.json into apko-ready YAML

Chainguard publishes per-image locked config files (e.g. images/static/locked_config.json, images/python/locked_config.json) that pin exact package versions for reproducible apko builds across architectures. To feed any combination into apko build you would otherwise have to: fetch the JSON, walk imageLocks.<variant>.configs.<arch>, JSON-decode the string value at that key (it's JSON encoded twice), unwrap the "config" field, and optionally re-serialize as YAML (though JSON can be used as-is too). This command does that for every variant × arch combination — including the -dev flavor under devConfigs when present — in one shot saving the config in a more human readable YAML format.

Takes one positional argument: a local file path or http(s):// URL pointing at a locked_config.json.

# Default: keep exact package version pins
wolfictl apk extract-locked-configs \
  https://raw.githubusercontent.com/chainguard-images/images/refs/heads/main/images/python/locked_config.json

# Strip the pins so apko resolves to whatever is latest at build time
wolfictl apk extract-locked-configs ./locked_config.json --exact-package-versions=false

Single optional flag:

Flag Default Description
--exact-package-versions true Keep the package version information from the locked config. Set to false to strip the package versions producing an unpinned apko config.

Output files are written into the current working directory using the pattern:

apko_config_<variant>[-dev]_<arch>.yaml

For the chainguard python image you get:

apko_config_python-public_index.yaml         # regular flavor, archs: [amd64, arm64]
apko_config_python-public-dev_index.yaml     # dev flavor    (the `-dev` image tag)

Worked example — the chainguard python locked config

wolfictl apk extract-locked-configs \
  https://raw.githubusercontent.com/chainguard-images/images/refs/heads/main/images/python/locked_config.json

Log output:

wrote /<cwd>/apko_config_python-public_index.yaml
wrote /<cwd>/apko_config_python-public-dev_index.yaml

Resulting files:

apko_config_python-public_index.yaml         # the `latest` image tag
apko_config_python-public-dev_index.yaml     # the `latest-dev` image tag

The top of apko_config_python-public_index.yaml looks like this (truncated):

contents:
    repositories:
        - https://apk.cgr.dev/chainguard
    packages:
        - ca-certificates-bundle=20260413-r0
        - gdbm=1.26-r5
        - glibc-locale-posix=2.43-r7
        - glibc=2.43-r7
        - ld-linux=2.43-r7
        - libbz2-1=1.0.8-r23
        - libcrypto3=3.6.2-r5
        - libffi=3.5.2-r7
        - libssl3=3.6.2-r5
        - libstdc++=16.1.0-r0
        - python-3.14=3.14.5-r1
        - sqlite-libs=3.53.1-r0
        - wolfi-baselayout=20230201-r29
        - zlib=1.3.2-r3
        # ...
entrypoint:
    command: /usr/bin/python
archs:
    - amd64
    - arm64
annotations:
    org.opencontainers.image.title: python
    org.opencontainers.image.vendor: Chainguard
    # ...

Re-running with --exact-package-versions=false strips the version pins so apko resolves the latest at build time:

wolfictl apk extract-locked-configs \
  https://raw.githubusercontent.com/chainguard-images/images/refs/heads/main/images/python/locked_config.json \
  --exact-package-versions=false

Same files, but the contents.packages list now reads:

contents:
    packages:
        - ca-certificates-bundle
        - gdbm
        - glibc-locale-posix
        - glibc
        - python-3.14
        - wolfi-baselayout
        # ...

Feeding the YAML to apko

Either YAML produced above (pinned or unpinned) is a valid input to apko. Three common workflows:

1) Preview the resolved package list — no build.

apko show-packages reads a config and prints the apks it would install, with versions resolved against the configured repositories. Useful for confirming the locked file produces the package set you expect.

apko show-packages apko_config_python-public_index.yaml

2) Build a single-arch tarball and load it into Docker.

The extracted YAML has archs: [amd64, arm64], so a plain apko build produces an OCI image index covering both archs. To target just your host architecture, pass --arch. The third argument is the output tarball path.

# Build only the amd64 image into a tarball
apko build --arch amd64 \
  apko_config_python-public_index.yaml \
  my-org/python-from-locked:latest \
  python-from-locked-amd64.tar

# Load the result into the local Docker daemon
docker load < python-from-locked-amd64.tar
docker run --rm my-org/python-from-locked:latest -c 'print("hello from a locked-config build")'

3) Build the multi-arch image and publish it to a registry.

apko publish builds for every arch listed in the YAML's archs: field (so by default both amd64 and arm64 for the extracted python config) and pushes an OCI index plus the per-arch images to the named tag. Auth uses whatever your Docker config / crane / cosign keychain provides.

apko publish \
  apko_config_python-public-dev_index.yaml \
  ghcr.io/my-org/python-dev-from-locked:latest \
  ghcr.io/my-org/python-dev-from-locked:latest-dev

Tip: the unpinned variant (--exact-package-versions=false) is the one you usually want for apko publish if you're rebuilding regularly and want freshness; the pinned variant is what you want for reproducing the exact same image Chainguard published. Run extract-locked-configs twice with different --exact-package-versions values and keep both YAMLs around if you need both modes.

Notable behavior:

  • Schema-validated output. The inner config is round-tripped through apko's own chainguard.dev/apko/pkg/build/types.ImageConfiguration struct, not a generic map[string]any. This guarantees the output uses apko's canonical YAML field names (stop-signal, work-dir, vcs-url, build_repositories, run-as, …) and drops the empty filler fields (cmd: "", environment: {}, layering: null, etc.) that the locked JSON ships with.
  • Multi-arch consolidation. The locked config carries amd64, arm64, AND an index entry per flavor. In every Chainguard locked config inspected, the per-arch entries are byte-identical to the index entry except for the archs field. When that's the case, the command emits a single consolidated apko_config_<variant>_index.yaml with archs: [amd64, arm64] instead of three near-duplicate files. If per-arch entries ever genuinely diverge, the command falls back automatically to emitting per-arch files alongside the index — full fidelity, data-driven.
  • Path-traversal guard. Variant/arch names that would escape the output directory ("../../foo" etc.) are rejected before any write. Important because the input is third-party JSON and the command will accept arbitrary URLs.
  • Empty devConfigs is skipped silently — images without a -dev flavor (like static) produce only the regular files.

Bug fix: wolfictl image apk no longer pulls in the RPM cataloger

wolfictl image apk analyzes wolfi/chainguard images and only ever reads APK packages from the resulting SBOM, but it was using syft's default cataloger set, which includes the RPM cataloger. On newer RPM DB formats syft's RPM cataloger requires a sqlite driver, so running the command failed with:

ERRO unable to create SBOM: failed to run tasks: sqlite driver is required for cataloging newer RPM databases, none registered: sql: unknown driver "sqlite" (forgotten import?)

Fix: the command now explicitly removes the rpm cataloger via cataloging.NewSelectionRequest().WithRemovals("rpm") when building the syft CreateSBOMConfig.

Installation

You can install wolfictl straight from its source code. To do this, clone the git repository and then run go install:

# Clone the repo

git clone git@github.com:wolfi-dev/wolfictl.git wolfictl && cd $_

# Install the `wolfictl` command

go install

Build a local binary into ./bin

If you'd rather drop the binary inside the repo (e.g. to keep multiple builds side-by-side, or to avoid touching $GOPATH/bin), build it with go build instead:

mkdir -p bin && go build -o bin/wolfictl .

This produces ./bin/wolfictl relative to the repo root. The mkdir -p bin step is needed because go build -o doesn't create the parent directory itself. Verify with:

./bin/wolfictl --help
./bin/wolfictl apk extract-locked-configs --help

Commands

See the wolfictl command reference

Docs

Check so_name docs - CI check for detecting ABI breaking changes in package version updates Update docs - for detecting new upstream wolfi package versions and creating a pull request to update Wolfi

Releases

This repo is configured to automatically create weekly tagged patch releases, mainly so that it can be more easily packaged in Wolfi itself.

Releases happen Monday at 00:00 UTC, and can be manually run as necessary.