Client

Automatically generated client from Dagger API.

class dagger.api.gen.BuildArg

name: str

value: str

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

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. “myapp- 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

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) → GitRepository

Queries a git repository.

host() → Host

Queries the host environment.

http(url: str) → File

Returns a file containing an http remote url content.

pipeline(name: str, description: str | None = None) → Client

Creates a named sub-pipeline

project(name: str) → Project

Look up a project by name

secret(id: SecretID) → Secret

Loads a secret from its ID.

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) → Container

Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs.

Parameters:

• context – Directory context used by the Dockerfile.

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

• build_args – Additional build arguments.

• target – Target build stage to build.

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]]

directory(path: str) → Directory

Retrieves a directory at the given path. Mounts are included.

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]]

env_variable(name: str) → str | None

Retrieves the value of the specified environment 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:

Optional[str]

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.

• stdin – Content to write to the command’s standard input before closing.

• redirect_stdout – Redirect the command’s standard output to a file in the container.

• redirect_stderr – Redirect the command’s standard error to a file in the container.

• 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 | None

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

Null if no command has been executed.

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:

Optional[int]

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

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

Return true on success.

Parameters:

• path – Host’s destination path. Path can be relative to the engine’s workdir or absolute.

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

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

file(path: str) → File

Retrieves a file at the given path. Mounts are included.

from_(address: str) → Container

Initializes this container from the base image published at the given address.

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().

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

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]

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]

pipeline(name: str, description: str | None = None) → Container

Creates a named sub-pipeline

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

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

Publishes this container as a new image to the specified address, for the platformVariants, returning a fully qualified ref.

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.

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

rootfs() → Directory

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

stderr() → str | None

The error stream of the last executed command.

Null if no command has been executed.

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]

stdout() → str | None

The output stream of the last executed command.

Null if no command has been executed.

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]

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]

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

Configures default arguments for future commands.

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

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

with_entrypoint(args: Sequence[str]) → Container

Retrieves this container but with a different command entrypoint.

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

Retrieves this container plus the given environment variable.

with_exec(args: Sequence[str], 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.

Parameters:

• args – Command to run instead of the container’s default command.

• stdin – Content to write to the command’s standard input before closing.

• redirect_stdout – Redirect the command’s standard output to a file in the container.

• redirect_stderr – Redirect the command’s standard error to a file in the container.

• 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.

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

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

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.

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

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

Parameters:

• path – Path to mount the cache volume at.

• cache – ID of the cache to mount.

• source – Directory to use as the cache volume’s root.

• sharing – Sharing mode of the cache volume.

with_mounted_directory(path: str, source: Directory) → Container

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

with_mounted_file(path: str, source: File) → Container

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

with_mounted_secret(path: str, source: Secret) → Container

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

with_mounted_temp(path: str) → Container

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

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

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

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.

with_unix_socket(path: str, source: Socket) → Container

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

with_user(name: str) → Container

Retrieves this containers with a different command user.

with_workdir(path: str) → Container

Retrieves this container with a different working directory.

without_env_variable(name: str) → Container

Retrieves this container minus the given environment variable.

without_label(name: str) → Container

Retrieves this container minus the given environment label.

without_mount(path: str) → Container

Retrieves this container after unmounting everything at the given path.

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.

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]

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.

directory(path: str) → Directory

Retrieves a directory at the given path.

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

Builds a new Docker container from this directory.

Parameters:

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

• platform – The platform to build.

• build_args – Additional build arguments.

• target – Target build stage to build.

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

Returns a list of files and directories at the given 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:

list[str]

export(path: str) → bool

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

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

file(path: str) → File

Retrieves a file at the given path.

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

load_project(config_path: str) → Project

load a project’s metadata

pipeline(name: str, description: str | None = None) → Directory

Creates a named sub-pipeline.

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 –

• directory –

• 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.

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

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

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

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

with_timestamps(timestamp: int) → Directory

Retrieves this directory with all file/dir timestamps set to the given time, in seconds from the Unix epoch.

without_directory(path: str) → Directory

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

without_file(path: str) → Directory

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

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

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

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

export(path: str) → bool

Writes the file to a file path on the host.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

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

secret() → Secret

Retrieves a secret referencing the contents of this file.

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

with_timestamps(timestamp: int) → File

Retrieves this file with its created/modified timestamps set to the given time, in seconds from the Unix epoch.

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

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.

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]

commit(id: str) → GitRef

Returns details on one commit.

tag(name: str) → GitRef

Returns details on one tag.

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]

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.

env_variable(name: str) → HostVariable

Accesses an environment variable on the host.

unix_socket(path: str) → Socket

Accesses a Unix socket on the host.

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.

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

An environment variable on the host environment.

secret() → Secret

A secret referencing the value of this variable.

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

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

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

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.Project(ctx: Context)

A set of scripts and/or extensions

extensions() → Project

extensions in this project

generated_code() → Directory

Code files generated by the SDKs in the project

install() → bool

install the project’s schema

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

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

schema() → str | None

schema provided by 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:

Optional[str]

sdk() → str | None

sdk used to generate code for and/or execute this 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:

Optional[str]

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

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

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

class dagger.api.gen.SocketID

A content-addressed socket identifier.