/ 
API-Docker-0.003
/ API::Docker::API::Exec

NAME

API::Docker::API::Exec - Docker Engine Exec API

VERSION

version 0.003

SYNOPSIS

my $docker = API::Docker->new;

# Create an exec instance
my $exec = $docker->exec->create($container_id,
    Cmd         => ['/bin/sh', '-c', 'echo hello'],
    AttachStdout => 1,
    AttachStderr => 1,
);

# Start the exec -- ArrayRef of { stream => ..., data => ... } frames
my $frames = $docker->exec->start($exec->{Id});
my $output = join '', map { $_->{data} } @$frames;

# The exit status comes from a separate call
my $exit = $docker->exec->inspect($exec->{Id})->{ExitCode};

# Inspect exec instance
my $info = $docker->exec->inspect($exec->{Id});

DESCRIPTION

This module provides methods for executing commands inside running containers using the Docker Exec API.

Accessed via $docker->exec.

client

Reference to API::Docker client. Weak reference to avoid circular dependencies.

create

my $exec = $exec->create($container_id,
    Cmd          => ['/bin/sh', '-c', 'echo hello'],
    AttachStdout => 1,
    AttachStderr => 1,
    Tty          => 0,
);

Create an exec instance. Returns hashref with Id.

Required config: Cmd (ArrayRef of command and arguments).

Common config keys: AttachStdin, AttachStdout, AttachStderr, Tty, Env, User, WorkingDir.

start

my $frames = $exec->start($exec_id, Detach => 0);

my $output = join '', map { $_->{data} } @$frames;

Start an exec instance. Returns an ArrayRef of frames in the same shape as "logs" in API::Docker::API::Containers:

[ { stream => 'stdout', data => "OUT\n" },
  { stream => 'stderr', data => "ERR\n" } ]

An exec instance created without a TTY multiplexes stdout and stderr into one framed stream, which this method demultiplexes. One created with a TTY has no frame headers and its output arrives as a single stream => 'raw' frame. A detached start produces no output, so it returns an empty ArrayRef.

The exit status is not part of this response. It comes from a separate call once the exec has finished:

my $exit = $exec->inspect($exec_id)->{ExitCode};

Options:

  • Detach - Run detached; the engine returns immediately and no output is streamed

  • Tty - Declares that this exec instance was created with a TTY. It is sent in the request body, where the engine expects it to match the Tty given to "create", and it also suppresses demultiplexing of the response. Framing is otherwise detected from the response bytes -- see "Detecting a framed stream" in API::Docker::Role::HTTP

resize

$exec->resize($exec_id, h => 40, w => 120);

Resize the TTY for an exec instance. Options: h (height), w (width).

inspect

my $info = $exec->inspect($exec_id);

Get information about an exec instance.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-api-docker/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.