@zuke/docker-compose

← API reference

`@zuke/docker-compose` — typed Docker Compose task wrappers for Zuke builds.

Symbols

#

ComposeProbe

type
type ComposeProbe = unknown

Probes whether a candidate Compose invocation is runnable on this host. Receives the binary-and-prefix argv (["docker", "compose"] or ["docker-compose"]) and resolves to true when it works. Injectable so detection can be unit-tested without a real Docker install.

#

defaultComposeProbe

function
async function defaultComposeProbe(argv: unknown): Promise<boolean>

The default ComposeProbe: run the candidate's version subcommand quietly and treat a zero exit as success. A missing binary resolves to false rather than throwing, so detection can fall through to the next candidate.

#

DockerComposeBuildSettings

class
class DockerComposeBuildSettings extends DockerComposeSettings

Settings for compose build.

MemberSignatureDoc
noCache noCache(): this Do not use the layer cache (--no-cache).
pull pull(): this Always attempt to pull newer base images (--pull).
buildArg buildArg(key: string, value: string): this Pass a build-time variable (--build-arg KEY=value); repeatable.
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeCommitSettings

class
class DockerComposeCommitSettings extends DockerComposeSettings

Settings for compose commit.

MemberSignatureDoc
service service(name: string): this The service whose container to commit (required).
reference reference(value: string): this The image reference to create, e.g. my-app:test.
author author(value: string): this Image author (--author).
message message(value: string): this Commit message (--message).
change change(...instructions: string[]): this Apply a Dockerfile instruction to the created image (--change).
index index(value: number): this Pick the replica to commit when the service has several (--index).
noPause noPause(): this Leave the container running during the commit (--pause=false). Compose pauses it by default so the filesystem cannot change mid-capture; turning that off trades a consistent image for uninterrupted service.
#

DockerComposeConfigSettings

class
class DockerComposeConfigSettings extends DockerComposeSettings

Settings for compose config.

MemberSignatureDoc
quietOutput quietOutput(): this Only validate, printing nothing (-q).
servicesOnly servicesOnly(): this Print the service names only (--services).
volumesOnly volumesOnly(): this Print the volume names only (--volumes).
format format(value: string): this Output format (--format), e.g. yaml or json.
#

DockerComposeCpSettings

class
class DockerComposeCpSettings extends DockerComposeSettings

Settings for compose cp.

Compose copies between a service container and the local filesystem, so exactly one side names a service. Naming both or neither is refused rather than handed to Compose as a path it cannot resolve.

MemberSignatureDoc
fromService fromService(service: string, path: PathLike): this Copy out of service at path (SERVICE:PATH).
fromLocal fromLocal(path: PathLike): this Copy out of a local path.
toService toService(service: string, path: PathLike): this Copy into service at path (SERVICE:PATH).
toLocal toLocal(path: PathLike): this Copy into a local path.
index index(value: number): this Pick the replica to copy from when the service has several (--index).
all all(): this Include containers created by compose run (--all).
archive archive(): this Preserve uid/gid information (--archive).
followLink followLink(): this Follow symbolic links in the source path (--follow-link).
#

DockerComposeCreateSettings

class
class DockerComposeCreateSettings extends DockerComposeSettings

Settings for compose create.

MemberSignatureDoc
services services(...names: string[]): this Restrict creation to these services.
build build(): this Build images before creating containers (--build).
noBuild noBuild(): this Never build, whatever the policy says (--no-build).
forceRecreate forceRecreate(): this Recreate containers even when their configuration has not changed (--force-recreate).
noRecreate noRecreate(): this Leave existing containers in place (--no-recreate).
removeOrphans removeOrphans(): this Remove containers for services no longer in the file (--remove-orphans).
quietPull quietPull(): this Pull without progress output (--quiet-pull).
pull pull(policy: DockerComposePullPolicy): this When to pull images before creating (--pull).
scale scale(service: string, replicas: number): this Create replicas containers for service (--scale).
yes yes(): this Answer every prompt affirmatively (--yes), so an unattended run cannot stall.
#

DockerComposeDownSettings

class
class DockerComposeDownSettings extends DockerComposeSettings

Settings for compose down.

MemberSignatureDoc
volumes volumes(): this Also remove named and anonymous volumes (-v).
removeOrphans removeOrphans(): this Remove containers for services no longer defined (--remove-orphans).
rmi rmi(type: string): this Remove images of the given type (--rmi), e.g. all or local.
timeout timeout(seconds: number): this Shutdown timeout in seconds (-t).
#

DockerComposeEventsSettings

class
class DockerComposeEventsSettings extends DockerComposeSettings

Settings for compose events.

MemberSignatureDoc
services services(...names: string[]): this Restrict the stream to these services.
json json(): this Emit each event as a JSON object (--json).
since since(timestamp: string): this Include events since a timestamp (--since).
until until(timestamp: string): this Stop streaming at a timestamp (--until). Without it the command streams until interrupted, so a build target that awaits it blocks — bound the run with this or with .killAfter(ms).
#

DockerComposeExecSettings

class
class DockerComposeExecSettings extends DockerComposeSettings

Settings for compose exec.

MemberSignatureDoc
service service(name: string): this The service whose container to exec into (required).
detach detach(): this Run in the background (-d).
noTty noTty(): this Disable pseudo-TTY allocation (-T).
workdir workdir(path: PathLike): this Working directory inside the container (-w).
envVar envVar(key: string, value: string): this Set an environment variable (-e KEY=value); repeatable.
commandArgs commandArgs(...args: Array<string | number>): this The command and arguments to execute.
#

DockerComposeExportSettings

class
class DockerComposeExportSettings extends DockerComposeSettings

Settings for compose export.

MemberSignatureDoc
service service(name: string): this The service whose container filesystem to export (required).
output output(path: PathLike): this Write the tar archive to a file (--output) instead of stdout. Prefer it: a tar stream captured as the command's stdout goes through Zuke's output buffer, which is text-shaped and size-capped.
index index(value: number): this Pick the replica to export when the service has several (--index).
#

DockerComposeImagesSettings

class
class DockerComposeImagesSettings extends DockerComposeListingSettings

Settings for compose images.

MemberSignatureDoc
services services(...names: string[]): this Restrict the listing to these services.
#

DockerComposeKillSettings

class
class DockerComposeKillSettings extends DockerComposeSettings

Settings for compose kill.

MemberSignatureDoc
services services(...names: string[]): this Restrict the kill to these services.
signal signal(name: string): this The signal to send (--signal), SIGKILL by default. Send SIGTERM to let a service run its shutdown path — kill skips the grace period stop gives it.
removeOrphans removeOrphans(): this Remove containers for services no longer in the file (--remove-orphans).
#

DockerComposeListingSettings

class
class DockerComposeListingSettings extends DockerComposeSettings

Shared by the listing subcommands that accept --format and --quiet.

--format json is what makes these readable by a build rather than by a person, so the convenience json spells it rather than leaving the caller to remember the value.

MemberSignatureDoc
format format(value: string): this Format the output (--format), e.g. table or json.
json json(): this Emit JSON (--format json).
quietOutput quietOutput(): this Print only identifiers or names (--quiet).
#

DockerComposeLogsSettings

class
class DockerComposeLogsSettings extends DockerComposeSettings

Settings for compose logs.

MemberSignatureDoc
follow follow(): this Stream new log output (-f).
timestamps timestamps(): this Prefix each line with a timestamp (-t).
tail tail(lines: number | all): this Show only the last N lines, or all (--tail).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeLsSettings

class
class DockerComposeLsSettings extends DockerComposeListingSettings

Settings for compose ls, which lists Compose projects rather than services.

MemberSignatureDoc
all all(): this Include stopped projects (--all).
filter filter(expression: string): this Filter the listing (--filter), e.g. name=my-project.
#

DockerComposePauseSettings

class
class DockerComposePauseSettings extends DockerComposeServiceListSettings

Settings for compose pause.

#

DockerComposePortSettings

class
class DockerComposePortSettings extends DockerComposeSettings

Settings for compose port, which prints the host address a service's container port was published on.

MemberSignatureDoc
service service(name: string): this The service to ask about (required).
privatePort privatePort(port: number): this The container-side port to look up (required).
protocol protocol(value: tcp | udp): this The protocol of the binding (--protocol), tcp by default.
index index(value: number): this Pick the replica to ask when the service has several (--index).
#

DockerComposePsSettings

class
class DockerComposePsSettings extends DockerComposeSettings

Settings for compose ps.

MemberSignatureDoc
all all(): this Show stopped containers too (-a).
quietOutput quietOutput(): this Only show container IDs (-q).
servicesOnly servicesOnly(): this Display services instead of containers (--services).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposePullPolicy

type
type DockerComposePullPolicy = always | missing | never

When compose up fetches images before starting: always on every start, missing only when the image is absent locally, never at all.

#

DockerComposePullSettings

class
class DockerComposePullSettings extends DockerComposeSettings

Settings for compose pull.

MemberSignatureDoc
ignorePullFailures ignorePullFailures(): this Continue past services whose pull fails (--ignore-pull-failures).
quietOutput quietOutput(): this Pull without printing progress (-q).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposePushSettings

class
class DockerComposePushSettings extends DockerComposeSettings

Settings for compose push.

MemberSignatureDoc
ignorePushFailures ignorePushFailures(): this Continue past services whose push fails (--ignore-push-failures).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeRestartSettings

class
class DockerComposeRestartSettings extends DockerComposeSettings

Settings for compose restart.

MemberSignatureDoc
timeout timeout(seconds: number): this Restart timeout in seconds (-t).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeRmSettings

class
class DockerComposeRmSettings extends DockerComposeSettings

Settings for compose rm.

MemberSignatureDoc
force force(): this Do not prompt for confirmation (-f).
stop stop(): this Stop the containers first if needed (-s).
volumes volumes(): this Also remove anonymous volumes (-v).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeRunSettings

class
class DockerComposeRunSettings extends DockerComposeSettings

Settings for compose run.

MemberSignatureDoc
service service(name: string): this The service to run (required).
rm rm(): this Remove the container after it exits (--rm).
detach detach(): this Run in the background (-d).
noDeps noDeps(): this Do not start linked services (--no-deps).
name name(value: string): this Assign a container name (--name).
envVar envVar(key: string, value: string): this Set an environment variable (-e KEY=value); repeatable.
commandArgs commandArgs(...args: Array<string | number>): this The command and arguments to run inside the container.
#

DockerComposeScaleSettings

class
class DockerComposeScaleSettings extends DockerComposeSettings

Settings for compose scale.

MemberSignatureDoc
scale scale(service: string, replicas: number): this Scale service to replicas instances; repeatable (required).
noDeps noDeps(): this Do not start linked services (--no-deps).
#

DockerComposeServiceListSettings

class
class DockerComposeServiceListSettings extends DockerComposeSettings

Settings shared by compose pause and compose unpause, which take only a service list.

MemberSignatureDoc
services services(...names: string[]): this Restrict the command to these services.
#

DockerComposeSettings

class
class DockerComposeSettings extends ToolSettings

Base for all Compose subcommand settings. Holds the invocation prefix (docker compose vs docker-compose) and the global options that precede every subcommand (-f, -p, --profile, …), and resolves the prefix at run time unless it was pinned with usePlugin/useStandalone.

MemberSignatureDoc
file file(path: PathLike): this Add a Compose file (-f); repeatable, order-significant.
projectName projectName(name: string): this Set the project name (-p).
profile profile(name: string): this Enable a service profile (--profile); repeatable.
projectDirectory projectDirectory(path: PathLike): this Set the project working directory (--project-directory).
envFile envFile(path: PathLike): this Load environment from a file (--env-file).
usePlugin usePlugin(): this Force the v2 plugin form (docker compose) and skip detection.
useStandalone useStandalone(): this Force the v1 standalone form (docker-compose) and skip detection.
run run(): Promise<CommandOutput> Resolve the invocation prefix (unless pinned) and run, so the same build works against either the v2 plugin or the v1 standalone binary.
#

DockerComposeStartSettings

class
class DockerComposeStartSettings extends DockerComposeSettings

Settings for compose start.

MemberSignatureDoc
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeStopSettings

class
class DockerComposeStopSettings extends DockerComposeSettings

Settings for compose stop.

MemberSignatureDoc
timeout timeout(seconds: number): this Shutdown timeout in seconds (-t).
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeTasks

const
const DockerComposeTasks: DockerComposeTasksApi

Typed task functions for Docker Compose (docker compose/docker-compose).

#

DockerComposeTasksApi

interface
interface DockerComposeTasksApi

The shape of DockerComposeTasks.

MemberSignatureDoc
up up(configure?: Configure<DockerComposeUpSettings>): Promise<CommandOutput> Create and start services: compose up.
down down(configure?: Configure<DockerComposeDownSettings>): Promise<CommandOutput> Stop and remove services: compose down.
build build(configure?: Configure<DockerComposeBuildSettings>): Promise<CommandOutput> Build service images: compose build.
pull pull(configure?: Configure<DockerComposePullSettings>): Promise<CommandOutput> Pull service images: compose pull.
push push(configure?: Configure<DockerComposePushSettings>): Promise<CommandOutput> Push service images: compose push.
run run(configure?: Configure<DockerComposeRunSettings>): Promise<CommandOutput> Run a one-off command: compose run.
exec exec(configure?: Configure<DockerComposeExecSettings>): Promise<CommandOutput> Exec into a running service: compose exec.
logs logs(configure?: Configure<DockerComposeLogsSettings>): Promise<CommandOutput> View service logs: compose logs.
ps ps(configure?: Configure<DockerComposePsSettings>): Promise<CommandOutput> List containers: compose ps.
config config(configure?: Configure<DockerComposeConfigSettings>): Promise<CommandOutput> Render the resolved configuration: compose config.
start start(configure?: Configure<DockerComposeStartSettings>): Promise<CommandOutput> Start existing services: compose start.
stop stop(configure?: Configure<DockerComposeStopSettings>): Promise<CommandOutput> Stop running services: compose stop.
restart restart(configure?: Configure<DockerComposeRestartSettings>): Promise<CommandOutput> Restart services: compose restart.
rm rm(configure?: Configure<DockerComposeRmSettings>): Promise<CommandOutput> Remove stopped service containers: compose rm.
create create(configure?: Configure<DockerComposeCreateSettings>): Promise<CommandOutput> Create containers without starting them: compose create.
kill kill(configure?: Configure<DockerComposeKillSettings>): Promise<CommandOutput> Force-stop service containers: compose kill.
pause pause(configure?: Configure<DockerComposePauseSettings>): Promise<CommandOutput> Pause services: compose pause.
unpause unpause(configure?: Configure<DockerComposeUnpauseSettings>): Promise<CommandOutput> Resume paused services: compose unpause.
scale scale(configure?: Configure<DockerComposeScaleSettings>): Promise<CommandOutput> Set service replica counts: compose scale.
wait wait(configure?: Configure<DockerComposeWaitSettings>): Promise<CommandOutput> Block until services stop: compose wait. Keeps the ordinary contract — a non-zero container status fails the target. Use DockerComposeTasksApi.waitExitCode when the status is the answer rather than a failure.
cp cp(configure?: Configure<DockerComposeCpSettings>): Promise<CommandOutput> Copy between a service container and the local filesystem: compose cp.
top top(configure?: Configure<DockerComposeTopSettings>): Promise<CommandOutput> Show running processes: compose top.
export export(configure?: Configure<DockerComposeExportSettings>): Promise<CommandOutput> Export a container filesystem as a tar archive: compose export.
commit commit(configure?: Configure<DockerComposeCommitSettings>): Promise<CommandOutput> Create an image from a container: compose commit.
images images(configure?: Configure<DockerComposeImagesSettings>): Promise<CommandOutput> List the images the containers use: compose images.
volumes volumes(configure?: Configure<DockerComposeVolumesSettings>): Promise<CommandOutput> List the project's volumes: compose volumes.
ls ls(configure?: Configure<DockerComposeLsSettings>): Promise<CommandOutput> List Compose projects: compose ls.
version version(configure?: Configure<DockerComposeVersionSettings>): Promise<CommandOutput> Report the Compose version: compose version.
port port(configure?: Configure<DockerComposePortSettings>): Promise<CommandOutput> Print a published port binding: compose port.
events events(configure?: Configure<DockerComposeEventsSettings>): Promise<CommandOutput> Stream container events: compose events.
waitExitCode waitExitCode(configure?: Configure<DockerComposeWaitSettings>): Promise<number> The exit status the waited-on container stopped with. compose wait exits with the container's own status, so every code is a legitimate answer and none is left to mean "compose broke". This hands the code back rather than failing the target, and still fails when compose never reached a container at all.
servicePort servicePort(configure?: Configure<DockerComposePortSettings>): Promise<number> The host port a service's container port was published on. The point of letting Compose pick an ephemeral port is asking which one it picked, which is what this returns.
composeVersion composeVersion(configure?: Configure<DockerComposeVersionSettings>): Promise<DockerComposeVersion> The installed Compose version, parsed from compose version --format json.
#

DockerComposeTopSettings

class
class DockerComposeTopSettings extends DockerComposeSettings

Settings for compose top.

MemberSignatureDoc
services services(...names: string[]): this Restrict the report to these services.
#

DockerComposeUnpauseSettings

class
class DockerComposeUnpauseSettings extends DockerComposeServiceListSettings

Settings for compose unpause.

#

DockerComposeUpSettings

class
class DockerComposeUpSettings extends DockerComposeSettings

Settings for compose up.

MemberSignatureDoc
detach detach(): this Run in the background (-d).
build build(): this Build images before starting (--build).
forceRecreate forceRecreate(): this Recreate containers even if unchanged (--force-recreate).
removeOrphans removeOrphans(): this Remove containers for services no longer defined (--remove-orphans).
wait wait(): this Wait until services are running/healthy (--wait).
abortOnContainerExit abortOnContainerExit(): this Stop all containers if any container stops (--abort-on-container-exit).
noDeps noDeps(): this Start only the named services, leaving their dependencies alone (--no-deps). Without it compose starts or recreates a dependency that is stopped or whose configuration changed. With an already-healthy stack the two agree, so the difference shows up only on the runs where a dependency was not ready — which is where a target that meant "just this service" wants to be explicit.
pull pull(policy: DockerComposePullPolicy): this When to fetch images before starting (--pull). always keeps a stack on the current published images rather than whatever was pulled last; missing fetches only what is absent locally; never uses what is there. Distinct from DockerComposeBuildSettings.pull, which is build --pull, and from the pull task, which is the subcommand — each mirrors its own command.
exitCodeFrom exitCodeFrom(service: string): this Exit with this service's container's exit code (--exit-code-from).
scale scale(service: string, instances: number): this Scale a service to N instances (--scale service=N); repeatable.
services services(...names: string[]): this Restrict to specific services (positional); optional.
#

DockerComposeVersion

interface
interface DockerComposeVersion

The version report compose version --format json emits.

MemberSignatureDoc
version version: string The Compose version string, e.g. v5.1.1.
#

DockerComposeVersionSettings

class
class DockerComposeVersionSettings extends DockerComposeSettings

Settings for compose version.

MemberSignatureDoc
format format(value: string): this Format the output (--format), pretty or json.
json json(): this Emit JSON (--format json).
short short(): this Print only the version number (--short).
#

DockerComposeVolumesSettings

class
class DockerComposeVolumesSettings extends DockerComposeListingSettings

Settings for compose volumes.

MemberSignatureDoc
services services(...names: string[]): this Restrict the listing to the volumes these services use.
#

DockerComposeWaitSettings

class
class DockerComposeWaitSettings extends DockerComposeSettings

Settings for compose wait.

The command blocks until the named services' containers stop, then exits with the first container's own exit status. That makes its exit code a result rather than a failure — see DockerComposeTasks.waitExitCode, which hands the code back instead of failing the target.

MemberSignatureDoc
services services(...names: string[]): this The services to wait on (required).
downProject downProject(): this Tear the project down once the first container stops (--down-project), so a test run cleans up after itself without a second command.
#

ReplicaIndex

class
class ReplicaIndex

The --index flag that picks one replica of a scaled service.

cp, export, commit and port all take it with the same meaning and the same rendering, so they hold one of these rather than four copies of the field and the argv.push that goes with it. Each still exposes its own setter, because the public surface is per-command.

MemberSignatureDoc
set set(value: number): void Record the replica to act on.
render render(): string[] The flag, if one was set.
#

resetComposeInvocationCache_

function
function resetComposeInvocationCache_(): void

Clear the cached Compose invocation so the next resolveComposeInvocation re-detects. Internal test seam — the trailing underscore signals it is not part of the stable public API.

#

resolveComposeInvocation

function
function resolveComposeInvocation(probe?: ComposeProbe): Promise<string[]>

Resolve how Docker Compose is invoked on this host: ["docker", "compose"] for the v2 plugin or ["docker-compose"] for the v1 standalone binary. The v2 plugin is preferred; if neither is runnable a ToolNotFoundError is raised. The result is cached after the first successful detection (a failed detection is not cached, so a later call retries). Pass a custom ComposeProbe to override how candidates are tested.

#

ServiceList

class
class ServiceList

The trailing service-name operands most Compose subcommands accept.

Same reasoning as ReplicaIndex: the list and the way it is appended are identical wherever it appears, so it lives here once. Each settings class still exposes its own services() setter, because which subcommands take the operand — and what it means for each — is part of the public surface.

MemberSignatureDoc
add add(names: unknown): void Add service names to the list.
isEmpty isEmpty(): boolean Whether any service was named.
render render(): string[] The names, in the order they were added.