Images

Images are OCI-compatible container images used to create containers. MacTain can pull images, list local images, inspect metadata, tag images, push images, and import or export OCI layouts.

Command Reference

Command	Description	Typical use
`mactain image pull <reference>`	Pulls an image from a registry.	Confirm registry access and prepare an image before container start.
`mactain image push <reference>`	Pushes a local image to a registry.	Publish an image after tagging or building.
`mactain image tag <source> <target>`	Tags an existing local image.	Create a registry-specific or workflow-specific reference.
`mactain image export <reference> --output oci=<path>`	Exports a local image as an OCI layout directory.	Move an image through a source-backed portable format.
`mactain image import <reference> --input oci=<path>`	Imports or registers an OCI layout as a local image.	Bring an OCI layout into MacTain image inventory.
`mactain image list`	Lists local images.	Inspect local image inventory before cleanup or container creation.
`mactain image inspect <reference>`	Shows image metadata.	Confirm the image MacTain will use.
`mactain image policy get`	Shows effective image network policy.	Confirm offline and auto-pull behavior.
`mactain image policy set`	Updates offline and auto-pull behavior.	Control whether MacTain can implicitly pull missing images.
`mactain image monitor add <reference>`	Adds or updates one monitored image.	Track image updates and optional restart behavior.
`mactain image monitor remove <reference>`	Removes a monitored image.	Stop tracking an image.
`mactain image monitor list`	Lists monitored images and status.	Inspect monitoring state.
`mactain image monitor check-now`	Triggers an immediate check.	Run a manual update check.
`mactain image monitor schedule get`	Shows the global monitoring schedule.	Confirm when checks run.
`mactain image monitor schedule set`	Sets the global monitoring schedule.	Configure daily, weekly, or monthly check timing.
`mactain image delete <reference>`	Deletes a local image.	Clean up unused local images.
`mactain image docs`	Shows built-in image examples.	Get installed-release examples from the CLI.

Defaults And Behavior

Image references should be fully qualified when possible, such as docker.io/library/nginx:latest.
image pull supports --refresh, --force, and --progress-json.
OCI layout import/export is supported with oci=<path>.
Docker archive tar import/export is not supported by the current source material.
Registry credentials are managed separately through mactain registry credentials.
image policy set --offline enables offline mode; --no-offline disables it.
image policy set --auto-pull-on-missing enables implicit pull when an image is missing locally; --no-auto-pull-on-missing disables it.
Image monitoring has per-image policy, but the check schedule is global.
image monitor add defaults scope to all unless a Blueprint scope is supplied.

Practical Use Cases

Use case: pull an image before starting a container

Use this when you want to verify registry access before creating a container.

mactain image pull docker.io/library/nginx:latest
mactain image inspect docker.io/library/nginx:latest

If the pull fails, check network access and registry credentials before debugging the container command.

Use case: list local images and find stale inventory

Use this when you want to see what MacTain already has locally.

mactain image list
mactain image list --filter registry=docker.io --json

Use JSON output for automation. Docker-style --format templates are not source-backed for MacTain image listing.

Use case: move an image through an OCI layout

Use this when you need to copy an image through an OCI layout directory.

mactain image export docker.io/library/nginx:latest --output oci=/tmp/nginx-oci
mactain image import localhost/nginx:copy --input oci=/tmp/nginx-oci

Current source material supports OCI layouts for import/export. Docker save/load tar archives are not supported yet.

Use case: configure private registry access

Use this when pulls or pushes require credentials. MacTain registry credentials are Keychain-backed.

mactain registry credentials set --help
mactain registry credentials test --help

Use command help for the exact credential flags before entering secrets. Do not paste registry passwords into docs, logs, or support requests.

Use case: control offline and auto-pull behavior

Use this when you want MacTain to avoid network image pulls or when you want missing images to be pulled automatically.

mactain image policy get
mactain image policy set --offline --no-auto-pull-on-missing
mactain image policy set --no-offline --auto-pull-on-missing

Use offline mode when you need deterministic local-only behavior. Disable offline mode before workflows that should pull missing or refreshed images.

Use case: monitor an image and check immediately

Use this when you want MacTain to track an image for updates.

mactain image monitor add docker.io/library/nginx:latest --no-auto-restart
mactain image monitor list
mactain image monitor check-now

Use --auto-restart only when you are comfortable with in-scope running containers restarting after an image update.

Use case: schedule image monitoring

Use this when monitored images should be checked on a predictable cadence.

mactain image monitor schedule set \
  --cadence weekly \
  --weekdays tue,fri \
  --time 23:00
mactain image monitor schedule get

For monthly schedules, use --day-of-month <1..31> instead of --weekdays.

Next Steps

Continue to Registry credentials for private registry access, or Networking when your image runs a service that needs to be reachable.