Circe (named after the Odyssean sorceress who transformed vessels and their contents) extracts and examines the contents of containers.
Looking for development docs? Click here!
Circe provides easy-to-use installation scripts for all major platforms.
Important
If you're using v0.4.0 or earlier, please use the installer attached to that specific GitHub release. The scripts below are only compatible with v0.5.0 and newer.
Install the latest version with:
curl -sSfL https://raw.githubusercontent.com/fossas/circe/main/install.sh | bash# Install to a specific directory
curl -sSfL https://raw.githubusercontent.com/fossas/circe/main/install.sh | bash -s -- -b /usr/local/bin
# Install a specific version
curl -sSfL https://raw.githubusercontent.com/fossas/circe/main/install.sh | bash -s -- -v v0.5.0
# Get help
curl -sSfL https://raw.githubusercontent.com/fossas/circe/main/install.sh | bash -s -- -hInstall the latest version with:
iwr -useb https://raw.githubusercontent.com/fossas/circe/main/install.ps1 | iex# Install to a specific directory
$BinDir="C:\tools"; iwr -useb https://raw.githubusercontent.com/fossas/circe/main/install.ps1 | iex
# Install a specific version
$Version="v0.5.0"; iwr -useb https://raw.githubusercontent.com/fossas/circe/main/install.ps1 | iexYou can also download the pre-compiled binaries from the releases page and install them manually.
Tip
Check the help output for more details.
Extracts the contents of the image to disk.
# Extracts the contents of the image to disk.
#
# Usage:
# circe extract <image> <target> [--layers <layers>] [--platform <platform>] [--overwrite]
#
# Arguments:
# <image>
# The image to extract. See image reference below for more details.
# <target>
# The directory to which the image is extracted.
#
# Options for `circe extract`:
# --layers
# squash: Combines all layers into a single layer (default).
# squash-other: Combines all layers except the base layer into a single layer.
# base: Excludes all layers except the base layer.
# separate: Exports each layer in a separate subdirectory.
# --platform
# Defaults to your current platform.
# Accepts the same values as `docker` (e.g. `linux/amd64`, `darwin/arm64`, etc).
# --overwrite
# If the target directory already exists, overwrite it.
# --layer-glob, --lg
# A glob pattern to filter layers to extract.
# Layers matching this pattern are extracted.
# --layer-regex, --lr
# A regex pattern to filter layers to extract.
# Layers matching this pattern are extracted.
# --file-glob, --fg
# A glob pattern to filter files to extract.
# Files matching this pattern are extracted.
# --file-regex, --fr
# A regex pattern to filter files to extract.
# Files matching this pattern are extracted.
# --username
# The username to use for authentication; "password" is also required if provided.
# --password
# The password to use for authentication; "username" is also required if provided.
circe extract docker.io/contribsys/faktory:latest ./faktory --layers squash --platform linux/amd64Lists the contents of an image.
# Lists the contents of the image.
#
# Usage:
# circe list <image> [--platform <platform>] [--username <username>] [--password <password>]
#
# Arguments:
# <image>
# The image to list. See image reference below for more details.
#
# Options for `circe list`:
# --platform
# Defaults to your current platform.
# Accepts the same values as `docker` (e.g. `linux/amd64`, `darwin/arm64`, etc).
# --username
# The username to use for authentication; "password" is also required if provided.
# --password
# The password to use for authentication; "username" is also required if provided.
circe list docker.io/contribsys/faktory:latestThe primary recommendation for referencing an image is to use the fully qualified reference, e.g.:
circe list docker.io/contribsys/faktory:latest
circe list docker.io/library/ubuntu:14.04
circe list some-host.dev/some-namespace/some-project/some-image:latest
circe list some-host.dev/some-namespace/some-project/some-image@sha256:123abcHowever, for convenience, you can specify a "partial image reference" in a few different ways:
# namespace + name + tag; infers to docker.io/contribsys/faktory:latest
circe list contribsys/faktory:latest
# namespace + name + digest; infers to docker.io/contribsys/faktory@sha256:123abc
circe list contribsys/faktory@sha256:123abc
# namespace + name; infers to docker.io/contribsys/faktory:latest
circe list contribsys/faktory
# name + tag; infers to docker.io/library/ubuntu:latest
circe list ubuntu:latest
# name + digest; infers to docker.io/library/ubuntu@sha256:123abc
circe list ubuntu@sha256:123abc
# name; infers to docker.io/library/ubuntu:latest
circe list ubuntuBy default, circe fills in docker.io for the registry and library for the namespace.
However, you can customize the registry and namespace by setting the OCI_BASE and OCI_NAMESPACE environment variables:
# Specify the registry and/or namespace:
export OCI_BASE=some-host.dev
export OCI_NAMESPACE=some-namespace
# namespace + name + tag; infers to some-host.dev/contribsys/faktory:latest
circe list contribsys/faktory:latest
# namespace + name + digest; infers to some-host.dev/contribsys/faktory@sha256:123abc
circe list contribsys/faktory@sha256:123abc
# namespace + name; infers to some-host.dev/contribsys/faktory:latest
circe list contribsys/faktory
# name + tag; infers to some-host.dev/some-namespace/ubuntu:latest
circe list ubuntu:latest
# name + digest; infers to some-host.dev/some-namespace/ubuntu@sha256:123abc
circe list ubuntu@sha256:123abc
# name; infers to some-host.dev/some-namespace/ubuntu:latest
circe list ubuntuThe overall recommendation is to use fully qualified references.
The intention with the ability to override OCI_BASE and OCI_NAMESPACE is to make setup easier for CI/CD pipelines
that need to extract multiple images from a custom host and/or namespace, but don't want to have to write scripts
to concatenate them into fully qualified references.
You can customize the platform used by circe by passing --platform.
This is then used as follows:
- If the image is not multi-platform, this is ignored.
- If the image is multi-platform, this is used to select the platform to extract.
- If the image does not publish the requested platform,
circereports this as an error.
- If the image does not publish the requested platform,
If the image is multi-platform and no --platform argument is provided,
the first available platform is chosen according to the following priority list:
- The first platform-independent image in the manifest
- The current platform
- The
linuxOS and the current architecture - The
linuxOS and theamd64architecture - The first image in the manifest
You can customize the layers extracted by circe by passing --layers.
The default is squash, which combines all layers into a single layer.
The other options are:
base: Excludes all layers except the base layer.separate: Exports each layer in a separate subdirectory.
Tip
The separate option also writes a layers.json file in the target directory,
which is a JSON-encoded array of layer directory names.
This array specifies the order of layer application in the image.
Set RUST_LOG=debug to get more detailed logs, and RUST_LOG=trace to get extremely detailed logs.
You can also filter to logs in a specific module (such as circe or circe_lib)
by setting RUST_LOG=circe=debug or RUST_LOG=circe_lib=debug.
Tip
In macOS and Linux, you can apply environment variables to a command without changing your environment;
for example: RUST_LOG=trace circe ....
These are somewhat "known issues", but mostly "things to keep in mind" when using circe.
Ideally we'll fix these in the future; feel free to make a contribution or open an issue letting us know if one of these is blocking you.
- circe does not currently download layers concurrently.
Since network transfer is effectively always the bottleneck, adding concurrent downloads would likely speed up
circesignificantly. That being said, as of our tests todaycirceis already about as fast asdocker pull && docker save.