Skip to main content
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   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  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
                        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