14 KiB
wolfictl
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/--limitare applied, so the same--offset N --limit Malways produces the same slice. - Bounded concurrency. Downloads run in parallel with a cap of 16 in-flight requests.
- Atomic writes. Each
.apkis downloaded to<name>.part, thenos.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
.apkfile. - Path-traversal guard. Package filenames that would escape the output directory are rejected (defense for users running against untrusted indexes).
- Resilient index rewrite. Unparseable
.apkfiles 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.ImageConfigurationstruct, not a genericmap[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 anindexentry per flavor. In every Chainguard locked config inspected, the per-arch entries are byte-identical to theindexentry except for thearchsfield. When that's the case, the command emits a single consolidatedapko_config_<variant>_index.yamlwitharchs: [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
devConfigsis skipped silently — images without a-devflavor (likestatic) 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.