CLI Reference

Synopsis

subcompose ( -h | --help | -? )

subcompose ( -v | --version )

subcompose ( -l | --list )
   [--compose-file=<filename>]

subcompose delete-containers
   [--debug] [--interpolate] [--all] [--unmanaged]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose delete-images
   [--debug] [--interpolate] [--unmanaged]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose preview
   [--debug] [--interpolate] [--unmanaged]
   [--var-file=<filename>] [--src-tag=<src_tag>]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose pull
   [--interpolate] [--unmanaged]
   [--var-file=<filename>] [--src-tag=<src_tag>]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose push
   [--interpolate] [--unmanaged]
   [--var-file=<filename>] [--src-tag=<src_tag>]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose run
   [--debug] [--interpolate] [--unmanaged]
   [--var-file=<filename>] [--src-tag=<src_tag>]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose stop
   [--debug] [--interpolate] [--unmanaged]
   [--service=<service_tag>]... [--group=<group_tag>]...
   [--compose-file=<filename>]

subcompose tag
   [--interpolate] [--unmanaged]
   [--var-file=<filename>] [--src-tag=<src_tag>]
   [--service=<service_tag>]... [--group=<group_tag>]...
   --registry=<registry> --dst-tag=<dst_tag>
   [--compose-file=<filename>]

subcompose validate
   [--debug] [--fix] [--compose-file=<filename>]

Commands

delete-containers

Remove containers for the selected services. This command stops and deletes containers matching the specified services or groups. Use --all to stop and remove all containers on the system, regardless of their management status. Useful for cleaning up your Docker environment or resetting service state. Combine with --unmanaged to exclude managed containers, or --debug for verbose output. Example:

subcompose delete-containers --service=api:latest --all

delete-images

Remove Docker images for the selected services. This deletes images from your local Docker registry, freeing disk space and ensuring outdated images are not reused. Use --service or --group to target specific images. Combine with --unmanaged to exclude managed images. Example:

subcompose delete-images --group=core:1.0.0

preview

Print the generated compose.yaml to standard output. This allows you to review or pipe the output directly into docker compose for ad-hoc runs. Use --var-file to inject variables, --src-tag to set image tags, and --interpolate for shell-style variable expansion. Example:

subcompose preview --var-file=vars.env | docker compose -f - up

pull

Pull Docker images for the selected services from their registry. Ensures your local environment uses the latest images. Use --service or --group to specify targets, --src-tag to set tags, and --var-file for variable substitution. Example:

subcompose pull --service=api:latest

push

Push Docker images for the selected services to a registry. Use this to upload built images to a remote registry for sharing or deployment. Specify services/groups, tags, and registry as needed. Example:

subcompose push --group=core --src-tag=1.0.0

run

Start the selected services using docker compose up -d. This launches containers in detached mode. Use --debug for verbose logs, --var-file for variable injection, and --interpolate for variable expansion. Example:

subcompose run --service=api:latest --debug

stop

Stop the selected services using docker compose stop. This halts running containers without removing them. Use --service or --group to specify targets, --debug for verbose output. Example:

subcompose stop --group=core

tag

Re-tag Docker images for the selected services and push them to a registry. Use --registry to specify the destination registry and --dst-tag for the new tag. Useful for promoting images between environments or registries. Example:

subcompose tag --service=api:latest --registry=myregistry.com --dst-tag=prod

validate

Validate groups and volume references in the compose file. Checks for configuration errors, missing references, or misconfigurations. Use --fix to automatically correct detected issues, and --debug for detailed output. Example:

subcompose validate --fix --debug

Options

-c <filename>, --compose-file=<filename>: Compose file to read. Defaults to compose.yaml.

-d, --debug: Enable verbose debug output.

-E <variable>, --env-var=<variable>: Set an environment variable used during substitution (e.g. -E AWS_REGION=eu-west-1).

-f <filename>, --var-file=<filename>: Load substitution variables from a file.

-g <group_tag>, --group=<group_tag>: Select a named group of services. Append :<tag> to pin an image tag for every service in the group (e.g. --group=core:1.0.0).

-h, -?, --help: Show the help screen and exit.

-i, --interpolate: Enable shell-style variable interpolation in image names.

-l, --list: List all available groups and services and exit.

-r <registry>, --registry=<registry>: Docker registry URL used by the tag command.

-s <service_tag>, --service=<service_tag>: Select an individual service. Append :<tag> to pin an image tag (e.g. --service=api:latest).

-t <src_tag>, --src-tag=<src_tag>: Default image tag applied to all selected services.

-T <dst_tag>, --dst-tag=<dst_tag>: Destination tag used by the tag command (e.g. -T 127.0.0.1:5000:mytag).

-u, --unmanaged: Exclude services marked x-subcompose-managed: true from the output.

-v, --version: Print the version and exit.

--all: Used with delete-containers to target all containers on the system.

--fix: Used with validate to automatically fix detected issues.

Examples

Here are some practical examples of using the subcompose CLI:

Delete all containers

Run this command:

subcompose delete-containers --all

Removes all containers from the system, regardless of their management status.

Delete images for a group

Run this command:

subcompose delete-images --group=core:1.0.0

Removes Docker images for all services in the ‘core’ group with tag ‘1.0.0’.

Preview compose file with variable substitution

Run this command:

subcompose preview --var-file=vars.env | docker compose -f - up

Generates a compose file with variables from ‘vars.env’ and pipes it to Docker Compose.

Pull latest image for a service

Run this command:

subcompose pull --service=api:latest

Pulls the latest image for the ‘api’ service.

Tag and push an image to a registry

Run this command:

subcompose tag --service=api:latest --registry=myregistry.com --dst-tag=prod

Re-tags the ‘api’ image as ‘prod’ and pushes it to ‘myregistry.com’.

Validate and fix compose file

Run this command:

subcompose validate --fix --debug

Validates the compose file and automatically fixes detected issues, with verbose output.