images - List and import images

List images in the project. Images are the filesystem snapshots that sandboxes run from – every non-disposable contree run produces a new one.

Examples

# List all images
contree images

# Filter by tag prefix
contree images --prefix=ubuntu

# Only tagged images
contree images --tagged

# Images created in the last hour
contree images --since=1h

# Find a specific image by UUID prefix
contree images --uuid=3f2a7b

# JSON output for scripting
contree -f json images --tagged | jq -r '.tag'

Help output

$ contree images --help usage: contree images [-h] [--prefix PREFIX] [-i UUID] [-a] [--since SINCE] [--until UNTIL]                       [--limit LIMIT]                       {list,ls,import} ... List and import sandbox images. Without a subcommand, lists images (same as ``images list``). Subcommands:   list (ls)     List images with filtering and pagination   import        Import image from a container registry positional arguments:   {list,ls,import}     list (ls)           List images     import              Import image from container registry options:   -h, --help            show this help message and exit   --prefix PREFIX       Filter by tag prefix   -i UUID, --uuid UUID  Filter by image UUID   -a, --all             Include untagged images (default: tagged only)   --since SINCE         Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.   --until UNTIL         Show images before. Parse +/- intervals (bare seconds or smhdMy) or                         ISO/date to UTC datetime.   --limit LIMIT         Stop after this many images and warn if more are available (default: 3000) examples:   contree images --prefix=ubuntu   contree images list --all   contree images import ubuntu:latest   contree images import ubuntu:{latest,noble,jammy}   contree images import ghcr.io/owner/image:tag for coding agents:   `images` / `images list` is read-only   `images import` spawns async import operations and polls until completion   supports brace expansion for batch imports   Ctrl+C cancels all active import operations agent note:   Before using this command in an automated workflow, read:     contree agent

Filtering

--prefix matches the beginning of the tag string. This is useful for browsing available base images:

contree images --prefix=python
contree images --prefix=common/

--since and --until accept either ISO timestamps or duration intervals like 1h, 30m, 7d.

Subcommands

images list

contree images list (alias ls) is the explicit form of the bare contree images invocation. Both share the same flag set – pick the explicit form when you want a command that reads symmetrically with images import, or in scripts that already use the subcommand style everywhere.

$ contree images list --help usage: contree images list [-h] [--prefix PREFIX] [-i UUID] [-a] [--since SINCE] [--until UNTIL]                            [--limit LIMIT] options:   -h, --help            show this help message and exit   --prefix PREFIX       Filter by tag prefix   -i UUID, --uuid UUID  Filter by image UUID   -a, --all             Include untagged images (default: tagged only)   --since SINCE         Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.   --until UNTIL         Show images before. Parse +/- intervals (bare seconds or smhdMy) or                         ISO/date to UTC datetime.   --limit LIMIT         Stop after this many images and warn if more are available (default: 3000)

images import

contree images import REF [REF ...] pulls one or more images from an external OCI registry into the project and waits for the import operation to finish. Each reference may be a docker:// URL or any form the platform accepts; multiple refs are imported sequentially with shared credentials, and Ctrl-C cancels the in-flight operation cleanly.

$ contree images import --help usage: contree images import [-h] [--username USERNAME] [--password PASSWORD] [-t TIMEOUT]                              refs [refs ...] positional arguments:   refs                  Image references (supports brace expansion) options:   -h, --help            show this help message and exit   --username USERNAME   Registry username (enables credentials)   --password PASSWORD   Registry password (prompted securely if --username given)   -t TIMEOUT, --timeout TIMEOUT                         Import timeout in seconds examples:   contree images import ubuntu:latest   contree images import --timeout 600 ubuntu:latest   contree images import docker.io/ubuntu:latest   contree images import docker://docker.io/ubuntu:latest   contree images import ghcr.io/ubuntu/ubuntu:latest   contree images import ubuntu:{latest,noble,jammy} for coding agents:   mutating command — creates import operations   all formats are normalised to docker://registry/path:tag   polls every 5 seconds until all operations complete   Ctrl+C cancels all active import operations

See also