Client

Automatically generated client from Dagger API.

class dagger.api.gen.BuildArg(name: str, value: str)

Key value object that represents a build argument.

name: str

The build argument name.

value: str

The build argument value.

class dagger.api.gen.CacheID

A global cache volume identifier.

class dagger.api.gen.CacheSharingMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Sharing mode of the cache volume.

LOCKED = 'LOCKED'

Shares the cache volume amongst many build pipelines, but will serialize the writes

PRIVATE = 'PRIVATE'

Keeps a cache volume for a single build pipeline

SHARED = 'SHARED'

Shares the cache volume amongst many build pipelines

class dagger.api.gen.CacheVolume(ctx: Context)

A directory whose contents persist across runs.

id() → CacheID

Note

This is lazyly evaluated, no operation is actually run.

Returns:

A global cache volume identifier.

Return type:

CacheID

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.Client(ctx: Context)

cache_volume(key: str) → CacheVolume

Constructs a cache volume for a given cache key.

Parameters:

key – A string identifier to target this cache volume (e.g., “modules- cache”).

container(id: ContainerID | None = None, platform: Platform | None = None) → Container

Loads a container from ID.

Null ID returns an empty container (scratch). Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder’s host.

default_platform() → Platform

The default platform of the builder.

Returns:

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

Return type:

Platform

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory(id: DirectoryID | None = None) → Directory

Load a directory by ID. No argument produces an empty directory.

file(id: FileID) → File

Loads a file by ID.

git(url: str, keep_git_dir: bool | None = None, experimental_service_host: Container | None = None) → GitRepository

Queries a git repository.

Parameters:

• url – Url of the git repository. Can be formatted as https://{host}/{owner}/{repo}, git@{host}/{owner}/{repo} Suffix “.git” is optional.

• keep_git_dir – Set to true to keep .git directory.

• experimental_service_host – A service which must be started before the repo is fetched.

host() → Host

Queries the host environment.

http(url: str, experimental_service_host: Container | None = None) → File

Returns a file containing an http remote url content.

Parameters:

• url – HTTP url to get the content from (e.g., “https://docs.dagger.io”).

• experimental_service_host – A service which must be started before the URL is fetched.

pipeline(name: str, description: str | None = None, labels: Sequence[PipelineLabel] | None = None) → Client

Creates a named sub-pipeline.

Parameters:

• name – Pipeline name.

• description – Pipeline description.

• labels – Pipeline labels.

project(id: ProjectID | None = None) → Project

Load a project from ID.

project_command(id: ProjectCommandID | None = None) → ProjectCommand

Load a project command from ID.

secret(id: SecretID) → Secret

Loads a secret from its ID.

set_secret(name: str, plaintext: str) → Secret

Sets a secret given a user defined name to its plaintext and returns the secret.

Parameters:

• name – The user defined name for this secret

• plaintext – The plaintext of the secret

socket(id: SocketID | None = None) → Socket

Loads a socket by its ID.

class dagger.api.gen.Container(ctx: Context)

An OCI-compatible container, also known as a docker container.

build(context: Directory, dockerfile: str | None = None, build_args: Sequence[BuildArg] | None = None, target: str | None = None, secrets: Sequence[Secret] | None = None) → Container

Initializes this container from a Dockerfile build.

Parameters:

• context – Directory context used by the Dockerfile.

• dockerfile – Path to the Dockerfile to use. Default: ‘./Dockerfile’.

• build_args – Additional build arguments.

• target – Target build stage to build.

• secrets – Secrets to pass to the build. They will be mounted at /run/secrets/[secret-name].

default_args() → list[str] | None

Retrieves default arguments for future commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[list[str]]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory(path: str) → Directory

Retrieves a directory at the given path.

Mounts are included.

Parameters:

path – The path of the directory to retrieve (e.g., “./src”).

endpoint(port: int | None = None, scheme: str | None = None) → str

Retrieves an endpoint that clients can use to reach this container.

If no port is specified, the first exposed port is used. If none exist an error is returned.

If a scheme is specified, a URL is returned. Otherwise, a host:port pair is returned.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters:

• port – The exposed port number for the endpoint

• scheme – Return a URL with the given scheme, eg. http for http://

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

entrypoint() → list[str] | None

Retrieves entrypoint to be prepended to the arguments of all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[list[str]]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

env_variable(name: str) → str | None

Retrieves the value of the specified environment variable.

Parameters:

name – The name of the environment variable to retrieve (e.g., “PATH”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

env_variables() → EnvVariable

Retrieves the list of environment variables passed to commands.

exec(args: Sequence[str] | None = None, stdin: str | None = None, redirect_stdout: str | None = None, redirect_stderr: str | None = None, experimental_privileged_nesting: bool | None = None) → Container

Retrieves this container after executing the specified command inside it.

Deprecated

Replaced by with_exec().

Parameters:

• args – Command to run instead of the container’s default command (e.g., [“run”, “main.go”]).

• stdin – Content to write to the command’s standard input before closing (e.g., “Hello world”).

• redirect_stdout – Redirect the command’s standard output to a file in the container (e.g., “/tmp/stdout”).

• redirect_stderr – Redirect the command’s standard error to a file in the container (e.g., “/tmp/stderr”).

• experimental_privileged_nesting – Provide dagger access to the executed command. Do not use this option unless you trust the command being executed. The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.

exit_code() → int

Exit code of the last executed command. Zero means success.

Will execute default command if none is set, or error if there’s no default.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

export(path: str, platform_variants: Sequence[Container] | None = None, forced_compression: ImageLayerCompression | None = None) → bool

Writes the container as an OCI tarball to the destination file path on the host for the specified platform variants.

Return true on success. It can also publishes platform variants.

Parameters:

• path – Host’s destination path (e.g., “./tarball”). Path can be relative to the engine’s workdir or absolute.

• platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

• forced_compression – Force each layer of the exported image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

exposed_ports() → Port

Retrieves the list of exposed ports.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

file(path: str) → File

Retrieves a file at the given path.

Mounts are included.

Parameters:

path – The path of the file to retrieve (e.g., “./README.md”).

from_(address: str) → Container

Initializes this container from a pulled base image.

Parameters:

address – Image’s address from its registry. Formatted as [host]/[user]/[repo]:[tag] (e.g., “docker.io/dagger/dagger:main”).

fs() → Directory

Retrieves this container’s root filesystem. Mounts are not included.

Deprecated

Replaced by rootfs().

hostname() → str

Retrieves a hostname which can be used by clients to reach this container.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

id() → ContainerID

A unique identifier for this container.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

A unique container identifier. Null designates an empty container (scratch).

Return type:

ContainerID

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

image_ref() → str | None

The unique image reference which can only be retrieved immediately after the ‘Container.From’ call.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

import_(source: File, tag: str | None = None) → Container

Reads the container from an OCI tarball.

NOTE: this involves unpacking the tarball to an OCI store on the host at $XDG_CACHE_DIR/dagger/oci. This directory can be removed whenever you like.

Parameters:

• source – File to read the container from.

• tag – Identifies the tag to import from the archive, if the archive bundles multiple tags.

label(name: str) → str | None

Retrieves the value of the specified label.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

labels() → Label

Retrieves the list of labels passed to container.

mounts() → list[str]

Retrieves the list of paths where a directory is mounted.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

pipeline(name: str, description: str | None = None, labels: Sequence[PipelineLabel] | None = None) → Container

Creates a named sub-pipeline

Parameters:

• name – Pipeline name.

• description – Pipeline description.

• labels – Pipeline labels.

platform() → Platform

The platform this container executes and publishes as.

Returns:

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

Return type:

Platform

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

publish(address: str, platform_variants: Sequence[Container] | None = None, forced_compression: ImageLayerCompression | None = None) → str

Publishes this container as a new image to the specified address.

Publish returns a fully qualified ref. It can also publish platform variants.

Parameters:

• address – Registry’s address to publish the image to. Formatted as [host]/[user]/[repo]:[tag] (e.g. “docker.io/dagger/dagger:main”).

• platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

• forced_compression – Force each layer of the published image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

rootfs() → Directory

Retrieves this container’s root filesystem. Mounts are not included.

stderr() → str

The error stream of the last executed command.

Will execute default command if none is set, or error if there’s no default.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

stdout() → str

The output stream of the last executed command.

Will execute default command if none is set, or error if there’s no default.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

sync() → Container

Forces evaluation of the pipeline in the engine.

It doesn’t run the default command if no exec has been set.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

user() → str | None

Retrieves the user to be set for all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_default_args(args: Sequence[str] | None = None) → Container

Configures default arguments for future commands.

Parameters:

args – Arguments to prepend to future executions (e.g., [“-v”, “–no- cache”]).

with_directory(path: str, directory: Directory, exclude: Sequence[str] | None = None, include: Sequence[str] | None = None, owner: str | None = None) → Container

Retrieves this container plus a directory written at the given path.

Parameters:

• path – Location of the written directory (e.g., “/tmp/directory”).

• directory – Identifier of the directory to write

• exclude – Patterns to exclude in the written directory (e.g., [“node_modules/**”, “.gitignore”, “.git/”]).

• include – Patterns to include in the written directory (e.g., [”*.go”, “go.mod”, “go.sum”]).

• owner – A user:group to set for the directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_entrypoint(args: Sequence[str]) → Container

Retrieves this container but with a different command entrypoint.

Parameters:

args – Entrypoint to use for future executions (e.g., [“go”, “run”]).

with_env_variable(name: str, value: str, expand: bool | None = None) → Container

Retrieves this container plus the given environment variable.

Parameters:

• name – The name of the environment variable (e.g., “HOST”).

• value – The value of the environment variable. (e.g., “localhost”).

• expand – Replace ${VAR} or $VAR in the value according to the current environment variables defined in the container (e.g., “/opt/bin:$PATH”).

with_exec(args: Sequence[str], skip_entrypoint: bool | None = None, stdin: str | None = None, redirect_stdout: str | None = None, redirect_stderr: str | None = None, experimental_privileged_nesting: bool | None = None, insecure_root_capabilities: bool | None = None) → Container

Retrieves this container after executing the specified command inside it.

Parameters:

• args – Command to run instead of the container’s default command (e.g., [“run”, “main.go”]). If empty, the container’s default command is used.

• skip_entrypoint – If the container has an entrypoint, ignore it for args rather than using it to wrap them.

• stdin – Content to write to the command’s standard input before closing (e.g., “Hello world”).

• redirect_stdout – Redirect the command’s standard output to a file in the container (e.g., “/tmp/stdout”).

• redirect_stderr – Redirect the command’s standard error to a file in the container (e.g., “/tmp/stderr”).

• experimental_privileged_nesting – Provides dagger access to the executed command. Do not use this option unless you trust the command being executed. The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.

• insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing docker run with the –privileged flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

with_exposed_port(port: int, protocol: NetworkProtocol | None = None, description: str | None = None) → Container

Expose a network port.

Exposed ports serve two purposes:

• For health checks and introspection, when running services

• For setting the EXPOSE OCI field when publishing the container

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters:

• port – Port number to expose

• protocol – Transport layer network protocol

• description – Optional port description

with_file(path: str, source: File, permissions: int | None = None, owner: str | None = None) → Container

Retrieves this container plus the contents of the given file copied to the given path.

Parameters:

• path – Location of the copied file (e.g., “/tmp/file.txt”).

• source – Identifier of the file to copy.

• permissions – Permission given to the copied file (e.g., 0600). Default: 0644.

• owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_fs(id: Directory) → Container

Initializes this container from this DirectoryID.

Deprecated

Replaced by with_rootfs().

with_label(name: str, value: str) → Container

Retrieves this container plus the given label.

Parameters:

• name – The name of the label (e.g., “org.opencontainers.artifact.created”).

• value – The value of the label (e.g., “2023-01-01T00:00:00Z”).

with_mounted_cache(path: str, cache: CacheVolume, source: Directory | None = None, sharing: CacheSharingMode | None = None, owner: str | None = None) → Container

Retrieves this container plus a cache volume mounted at the given path.

Parameters:

• path – Location of the cache directory (e.g., “/cache/node_modules”).

• cache – Identifier of the cache volume to mount.

• source – Identifier of the directory to use as the cache volume’s root.

• sharing – Sharing mode of the cache volume.

• owner – A user:group to set for the mounted cache directory. Note that this changes the ownership of the specified mount along with the initial filesystem provided by source (if any). It does not have any effect if/when the cache has already been created. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_directory(path: str, source: Directory, owner: str | None = None) → Container

Retrieves this container plus a directory mounted at the given path.

Parameters:

• path – Location of the mounted directory (e.g., “/mnt/directory”).

• source – Identifier of the mounted directory.

• owner – A user:group to set for the mounted directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_file(path: str, source: File, owner: str | None = None) → Container

Retrieves this container plus a file mounted at the given path.

Parameters:

• path – Location of the mounted file (e.g., “/tmp/file.txt”).

• source – Identifier of the mounted file.

• owner – A user or user:group to set for the mounted file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_secret(path: str, source: Secret, owner: str | None = None) → Container

Retrieves this container plus a secret mounted into a file at the given path.

Parameters:

• path – Location of the secret file (e.g., “/tmp/secret.txt”).

• source – Identifier of the secret to mount.

• owner – A user:group to set for the mounted secret. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_temp(path: str) → Container

Retrieves this container plus a temporary directory mounted at the given path.

Parameters:

path – Location of the temporary directory (e.g., “/tmp/temp_dir”).

with_new_file(path: str, contents: str | None = None, permissions: int | None = None, owner: str | None = None) → Container

Retrieves this container plus a new file written at the given path.

Parameters:

• path – Location of the written file (e.g., “/tmp/file.txt”).

• contents – Content of the file to write (e.g., “Hello world!”).

• permissions – Permission given to the written file (e.g., 0600). Default: 0644.

• owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_registry_auth(address: str, username: str, secret: Secret) → Container

Retrieves this container with a registry authentication for a given address.

Parameters:

• address – Registry’s address to bind the authentication to. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

• username – The username of the registry’s account (e.g., “Dagger”).

• secret – The API key, password or token to authenticate to this registry.

with_rootfs(id: Directory) → Container

Initializes this container from this DirectoryID.

with_secret_variable(name: str, secret: Secret) → Container

Retrieves this container plus an env variable containing the given secret.

Parameters:

• name – The name of the secret variable (e.g., “API_SECRET”).

• secret – The identifier of the secret value.

with_service_binding(alias: str, service: Container) → Container

Establish a runtime dependency on a service.

The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.

The service will be reachable from the container via the provided hostname alias.

The service dependency will also convey to any files or directories produced by the container.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters:

• alias – A name that can be used to reach the service from the container

• service – Identifier of the service container

with_unix_socket(path: str, source: Socket, owner: str | None = None) → Container

Retrieves this container plus a socket forwarded to the given Unix socket path.

Parameters:

• path – Location of the forwarded Unix socket (e.g., “/tmp/socket”).

• source – Identifier of the socket to forward.

• owner – A user:group to set for the mounted socket. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_user(name: str) → Container

Retrieves this container with a different command user.

Parameters:

name – The user to set (e.g., “root”).

with_workdir(path: str) → Container

Retrieves this container with a different working directory.

Parameters:

path – The path to set as the working directory (e.g., “/app”).

without_env_variable(name: str) → Container

Retrieves this container minus the given environment variable.

Parameters:

name – The name of the environment variable (e.g., “HOST”).

without_exposed_port(port: int, protocol: NetworkProtocol | None = None) → Container

Unexpose a previously exposed port.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters:

• port – Port number to unexpose

• protocol – Port protocol to unexpose

without_label(name: str) → Container

Retrieves this container minus the given environment label.

Parameters:

name – The name of the label to remove (e.g., “org.opencontainers.artifact.created”).

without_mount(path: str) → Container

Retrieves this container after unmounting everything at the given path.

Parameters:

path – Location of the cache directory (e.g., “/cache/node_modules”).

without_registry_auth(address: str) → Container

Retrieves this container without the registry authentication of a given address.

Parameters:

address – Registry’s address to remove the authentication from. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

without_unix_socket(path: str) → Container

Retrieves this container with a previously added Unix socket removed.

Parameters:

path – Location of the socket to remove (e.g., “/tmp/socket”).

workdir() → str | None

Retrieves the working directory for all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.ContainerID

A unique container identifier. Null designates an empty container (scratch).

class dagger.api.gen.Directory(ctx: Context)

A directory.

diff(other: Directory) → Directory

Gets the difference between this directory and an another directory.

Parameters:

other – Identifier of the directory to compare.

directory(path: str) → Directory

Retrieves a directory at the given path.

Parameters:

path – Location of the directory to retrieve (e.g., “/src”).

docker_build(dockerfile: str | None = None, platform: Platform | None = None, build_args: Sequence[BuildArg] | None = None, target: str | None = None, secrets: Sequence[Secret] | None = None) → Container

Builds a new Docker container from this directory.

Parameters:

• dockerfile – Path to the Dockerfile to use (e.g., “frontend.Dockerfile”). Defaults: ‘./Dockerfile’.

• platform – The platform to build.

• build_args – Build arguments to use in the build.

• target – Target build stage to build.

• secrets – Secrets to pass to the build. They will be mounted at /run/secrets/[secret-name].

entries(path: str | None = None) → list[str]

Returns a list of files and directories at the given path.

Parameters:

path – Location of the directory to look at (e.g., “/src”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

export(path: str) → bool

Writes the contents of the directory to a path on the host.

Parameters:

path – Location of the copied directory (e.g., “logs/”).

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

file(path: str) → File

Retrieves a file at the given path.

Parameters:

path – Location of the file to retrieve (e.g., “README.md”).

id() → DirectoryID

The content-addressed identifier of the directory.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

A content-addressed directory identifier.

Return type:

DirectoryID

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

pipeline(name: str, description: str | None = None, labels: Sequence[PipelineLabel] | None = None) → Directory

Creates a named sub-pipeline

Parameters:

• name – Pipeline name.

• description – Pipeline description.

• labels – Pipeline labels.

with_directory(path: str, directory: Directory, exclude: Sequence[str] | None = None, include: Sequence[str] | None = None) → Directory

Retrieves this directory plus a directory written at the given path.

Parameters:

• path – Location of the written directory (e.g., “/src/”).

• directory – Identifier of the directory to copy.

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

with_file(path: str, source: File, permissions: int | None = None) → Directory

Retrieves this directory plus the contents of the given file copied to the given path.

Parameters:

• path – Location of the copied file (e.g., “/file.txt”).

• source – Identifier of the file to copy.

• permissions – Permission given to the copied file (e.g., 0600). Default: 0644.

with_new_directory(path: str, permissions: int | None = None) → Directory

Retrieves this directory plus a new directory created at the given path.

Parameters:

• path – Location of the directory created (e.g., “/logs”).

• permissions – Permission granted to the created directory (e.g., 0777). Default: 0755.

with_new_file(path: str, contents: str, permissions: int | None = None) → Directory

Retrieves this directory plus a new file written at the given path.

Parameters:

• path – Location of the written file (e.g., “/file.txt”).

• contents – Content of the written file (e.g., “Hello world!”).

• permissions – Permission given to the copied file (e.g., 0600). Default: 0644.

with_timestamps(timestamp: int) → Directory

Retrieves this directory with all file/dir timestamps set to the given time.

Parameters:

timestamp – Timestamp to set dir/files in. Formatted in seconds following Unix epoch (e.g., 1672531199).

without_directory(path: str) → Directory

Retrieves this directory with the directory at the given path removed.

Parameters:

path – Location of the directory to remove (e.g., “.github/”).

without_file(path: str) → Directory

Retrieves this directory with the file at the given path removed.

Parameters:

path – Location of the file to remove (e.g., “/file.txt”).

class dagger.api.gen.DirectoryID

A content-addressed directory identifier.

class dagger.api.gen.EnvVariable(ctx: Context)

A simple key value object that represents an environment variable.

name() → str

The environment variable name.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

value() → str

The environment variable value.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.File(ctx: Context)

A file.

contents() → str

Retrieves the contents of the file.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

export(path: str) → bool

Writes the file to a file path on the host.

Parameters:

path – Location of the written directory (e.g., “output.txt”).

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

id() → FileID

Retrieves the content-addressed identifier of the file.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

A file identifier.

Return type:

FileID

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

secret() → Secret

Retrieves a secret referencing the contents of this file.

Deprecated

insecure, leaves secret in cache. Superseded by set_secret()

size() → int

Gets the size of the file, in bytes.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_timestamps(timestamp: int) → File

Retrieves this file with its created/modified timestamps set to the given time.

Parameters:

timestamp – Timestamp to set dir/files in. Formatted in seconds following Unix epoch (e.g., 1672531199).

class dagger.api.gen.FileID

A file identifier.

class dagger.api.gen.GitRef(ctx: Context)

A git ref (tag, branch or commit).

digest() → str

The digest of the current value of this ref.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

tree(ssh_known_hosts: str | None = None, ssh_auth_socket: Socket | None = None) → Directory

The filesystem tree at this ref.

class dagger.api.gen.GitRepository(ctx: Context)

A git repository.

branch(name: str) → GitRef

Returns details on one branch.

Parameters:

name – Branch’s name (e.g., “main”).

branches() → list[str]

Lists of branches on the repository.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

commit(id: str) → GitRef

Returns details on one commit.

Parameters:

id – Identifier of the commit (e.g., “b6315d8f2810962c601af73f86831f6866ea798b”).

tag(name: str) → GitRef

Returns details on one tag.

Parameters:

name – Tag’s name (e.g., “v0.3.9”).

tags() → list[str]

Lists of tags on the repository.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.Host(ctx: Context)

Information about the host execution environment.

directory(path: str, exclude: Sequence[str] | None = None, include: Sequence[str] | None = None) → Directory

Accesses a directory on the host.

Parameters:

• path – Location of the directory to access (e.g., “.”).

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

env_variable(name: str) → HostVariable

Accesses an environment variable on the host.

Parameters:

name – Name of the environment variable (e.g., “PATH”).

unix_socket(path: str) → Socket

Accesses a Unix socket on the host.

Parameters:

path – Location of the Unix socket (e.g., “/var/run/docker.sock”).

workdir(exclude: Sequence[str] | None = None, include: Sequence[str] | None = None) → Directory

Retrieves the current working directory on the host.

Deprecated

Use directory() with path set to ‘.’ instead.

Parameters:

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

class dagger.api.gen.HostVariable(ctx: Context)

An environment variable on the host environment.

secret() → Secret

A secret referencing the value of this variable.

Deprecated

been superseded by set_secret()

value() → str

The value of this variable.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.ImageLayerCompression(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Compression algorithm to use for image layers

EStarGZ = 'EStarGZ'

Gzip = 'Gzip'

Uncompressed = 'Uncompressed'

Zstd = 'Zstd'

class dagger.api.gen.Label(ctx: Context)

A simple key value object that represents a label.

name() → str

The label name.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

value() → str

The label value.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.NetworkProtocol(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Transport layer network protocol associated to a port.

TCP(Transmission Control Protocol) = 'TCP'

TCP (Transmission Control Protocol)

UDP(User Datagram Protocol) = 'UDP'

UDP (User Datagram Protocol)

class dagger.api.gen.PipelineLabel(name: str, value: str)

Key value object that represents a Pipeline label.

name: str

Label name.

value: str

Label value.

class dagger.api.gen.Platform

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

class dagger.api.gen.Port(ctx: Context)

A port exposed by a container.

description() → str | None

The port description.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

port() → int

The port number.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

protocol() → NetworkProtocol

The transport layer network protocol.

Returns:

Transport layer network protocol associated to a port.

Return type:

NetworkProtocol

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.Project(ctx: Context)

A collection of Dagger resources that can be queried and invoked.

commands() → ProjectCommand

Commands provided by this project

id() → str

A unique identifier for this project.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

load(source: Directory, config_path: str) → Project

Initialize this project from the given directory and config path

name() → str

Name of the project

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.ProjectCommand(ctx: Context)

A command defined in a project that can be invoked from the CLI.

description() → str | None

Documentation for what this command does.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

flags() → ProjectCommandFlag

Flags accepted by this command.

id() → str

A unique identifier for this command.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

name() → str

The name of the command.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

subcommands() → ProjectCommand

Subcommands, if any, that this command provides.

class dagger.api.gen.ProjectCommandFlag(ctx: Context)

A flag accepted by a project command.

description() → str | None

Documentation for what this flag sets.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

Optional[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

name() → str

The name of the flag.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.ProjectCommandID

A unique project command identifier.

class dagger.api.gen.ProjectID

A unique project identifier.

class dagger.api.gen.Secret(ctx: Context)

A reference to a secret value, which can be handled more safely than the value itself.

id() → SecretID

The identifier for this secret.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

A unique identifier for a secret.

Return type:

SecretID

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

plaintext() → str

The value of this secret.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.SecretID

A unique identifier for a secret.

class dagger.api.gen.Socket(ctx: Context)

id() → SocketID

The content-addressed identifier of the socket.

Note

This is lazyly evaluated, no operation is actually run.

Returns:

A content-addressed socket identifier.

Return type:

SocketID

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.api.gen.SocketID

A content-addressed socket identifier.