Dagger GraphQL API Reference

Queries

blob

Description

Retrieves a content-addressed blob.

Type

Directory!

Arguments
Name Description
digest - String! Digest of the blob
mediaType - String! Media type of the blob
size - Int! Size of the blob
uncompressed - String! Digest of the uncompressed blob
Example

builtinContainer

Description

Retrieves a container builtin to the engine.

Type

Container!

Arguments
Name Description
digest - String! Digest of the image manifest
Example

cacheVolume

Description

Constructs a cache volume for a given cache key.

Arguments
Name Description
key - String! A string identifier to target this cache volume (e.g., "modules-cache").
Example
query {
  cacheVolume(key: "deps") {
    id
  }
}

Try it in the API Playground!

container

Description

Creates a scratch container.

Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.

Type

Container!

Arguments
Name Description
platform - Platform Platform to initialize the container with.
Example
query {
  container {
    from(address: "alpine") {
      defaultArgs
      entrypoint
      platform
      rootfs {
        entries
      }
    }
  }
}

Try it in the API Playground!

currentFunctionCall

Description

The FunctionCall context that the SDK caller is currently executing in.

If the caller is not currently executing in a function, this will return an error.

Example

currentModule

Description

The module currently being served in the session, if any.

Example

currentTypeDefs

Description

The TypeDef representations of the objects currently being served in the session.

Example

daggerEngine

Description

The Dagger engine container configuration and state

Example

defaultPlatform

Description

The default platform of the engine.

Type

Platform!

Example
query {
  defaultPlatform
}

Try it in the API Playground!

directory

Description

Creates an empty directory.

Type

Directory!

Example
query {
  directory {
    withNewDirectory(path: "foo") {
      withNewDirectory(path: "foo/bar/baz") {
        withNewFile(path: "foo/bar/greeting", contents: "hello, world!\n") {
          foo: entries(path: "foo")
          bar: entries(path: "foo/bar")
          greeting: file(path: "foo/bar/greeting") {
            contents
          }
        }
      }
    }
  }
}

Try it in the API Playground!

function

Description

Creates a function.

Type

Function!

Arguments
Name Description
name - String! Name of the function, in its original format from the implementation language.
returnType - TypeDefID! Return type of the function.
Example

generatedCode

Description

Create a code generation result, given a directory containing the generated code.

Arguments
Name Description
code - DirectoryID!
Example

git

Description

Queries a Git repository.

Arguments
Name Description
experimentalServiceHost - ServiceID A service which must be started before the repo is fetched.
keepGitDir - Boolean Set to true to keep .git directory. Default = false
sshAuthSocket - SocketID Set SSH auth socket
sshKnownHosts - String Set SSH known hosts. Default = ""
url - String!

URL of the git repository.

Can be formatted as https://{host}/{owner}/{repo}, git@{host}:{owner}/{repo}.

Suffix ".git" is optional.

Example
query {
  git(url: "https://github.com/dagger/dagger", keepGitDir: true) {
    branch(name: "main") {
      tree {
        file(path: ".git/refs/heads/main") {
          contents
        }
      }
    }
  }
}

Try it in the API Playground!

host

Description

Queries the host environment.

Type

Host!

Example
query {
  host {
    read: directory(path: ".") {
      file(path: ".markdownlint.yaml") {
        contents
      }
    }
    home: envVariable(name: "HOME") {
      value
    }
    pwd: envVariable(name: "PWD") {
      value
    }
    write: directory(path: ".") {
      withNewFile(path: "greeting", contents: "Hello Dagger!") {
        export(path: ".")
      }
    }
  }
}

Try it in the API Playground!

http

Description

Returns a file containing an http remote url content.

Type

File!

Arguments
Name Description
experimentalServiceHost - ServiceID A service which must be started before the URL is fetched.
url - String! HTTP url to get the content from (e.g., "https://docs.dagger.io").
Example
query {
  http(url: "http://dagger.io") {
    size
    contents
  }
}

Try it in the API Playground!

loadCacheVolumeFromID

Description

Load a CacheVolume from its ID.

Arguments
Name Description
id - CacheVolumeID!
Example

loadContainerFromID

Description

Load a Container from its ID.

Type

Container!

Arguments
Name Description
id - ContainerID!
Example

loadCurrentModuleFromID

Description

Load a CurrentModule from its ID.

Arguments
Name Description
id - CurrentModuleID!
Example

loadDaggerEngineCacheEntryFromID

Description

Load a DaggerEngineCacheEntry from its ID.

Arguments
Name Description
id - DaggerEngineCacheEntryID!
Example

loadDaggerEngineCacheEntrySetFromID

Description

Load a DaggerEngineCacheEntrySet from its ID.

Arguments
Name Description
id - DaggerEngineCacheEntrySetID!
Example

loadDaggerEngineCacheFromID

Description

Load a DaggerEngineCache from its ID.

Arguments
Name Description
id - DaggerEngineCacheID!
Example

loadDaggerEngineFromID

Description

Load a DaggerEngine from its ID.

Arguments
Name Description
id - DaggerEngineID!
Example

loadDirectoryFromID

Description

Load a Directory from its ID.

Type

Directory!

Arguments
Name Description
id - DirectoryID!
Example

loadEnumTypeDefFromID

Description

Load a EnumTypeDef from its ID.

Arguments
Name Description
id - EnumTypeDefID!
Example

loadEnumValueTypeDefFromID

Description

Load a EnumValueTypeDef from its ID.

Arguments
Name Description
id - EnumValueTypeDefID!
Example

loadEnvVariableFromID

Description

Load a EnvVariable from its ID.

Arguments
Name Description
id - EnvVariableID!
Example

loadFieldTypeDefFromID

Description

Load a FieldTypeDef from its ID.

Arguments
Name Description
id - FieldTypeDefID!
Example

loadFileFromID

Description

Load a File from its ID.

Type

File!

Arguments
Name Description
id - FileID!
Example

loadFunctionArgFromID

Description

Load a FunctionArg from its ID.

Arguments
Name Description
id - FunctionArgID!
Example

loadFunctionCallArgValueFromID

Description

Load a FunctionCallArgValue from its ID.

Arguments
Name Description
id - FunctionCallArgValueID!
Example

loadFunctionCallFromID

Description

Load a FunctionCall from its ID.

Arguments
Name Description
id - FunctionCallID!
Example

loadFunctionFromID

Description

Load a Function from its ID.

Type

Function!

Arguments
Name Description
id - FunctionID!
Example

loadGeneratedCodeFromID

Description

Load a GeneratedCode from its ID.

Arguments
Name Description
id - GeneratedCodeID!
Example

loadGitModuleSourceFromID

Description

Load a GitModuleSource from its ID.

Arguments
Name Description
id - GitModuleSourceID!
Example

loadGitRefFromID

Description

Load a GitRef from its ID.

Type

GitRef!

Arguments
Name Description
id - GitRefID!
Example

loadGitRepositoryFromID

Description

Load a GitRepository from its ID.

Arguments
Name Description
id - GitRepositoryID!
Example

loadHostFromID

Description

Load a Host from its ID.

Type

Host!

Arguments
Name Description
id - HostID!
Example

loadInputTypeDefFromID

Description

Load a InputTypeDef from its ID.

Arguments
Name Description
id - InputTypeDefID!
Example

loadInterfaceTypeDefFromID

Description

Load a InterfaceTypeDef from its ID.

Arguments
Name Description
id - InterfaceTypeDefID!
Example

loadLabelFromID

Description

Load a Label from its ID.

Type

Label!

Arguments
Name Description
id - LabelID!
Example

loadListTypeDefFromID

Description

Load a ListTypeDef from its ID.

Arguments
Name Description
id - ListTypeDefID!
Example

loadLocalModuleSourceFromID

Description

Load a LocalModuleSource from its ID.

Arguments
Name Description
id - LocalModuleSourceID!
Example

loadModuleDependencyFromID

Description

Load a ModuleDependency from its ID.

Arguments
Name Description
id - ModuleDependencyID!
Example

loadModuleFromID

Description

Load a Module from its ID.

Type

Module!

Arguments
Name Description
id - ModuleID!
Example

loadModuleSourceFromID

Description

Load a ModuleSource from its ID.

Arguments
Name Description
id - ModuleSourceID!
Example

loadModuleSourceViewFromID

Description

Load a ModuleSourceView from its ID.

Arguments
Name Description
id - ModuleSourceViewID!
Example

loadObjectTypeDefFromID

Description

Load a ObjectTypeDef from its ID.

Arguments
Name Description
id - ObjectTypeDefID!
Example

loadPortFromID

Description

Load a Port from its ID.

Type

Port!

Arguments
Name Description
id - PortID!
Example

loadScalarTypeDefFromID

Description

Load a ScalarTypeDef from its ID.

Arguments
Name Description
id - ScalarTypeDefID!
Example

loadSecretFromID

Description

Load a Secret from its ID.

Type

Secret!

Arguments
Name Description
id - SecretID!
Example

loadServiceFromID

Description

Load a Service from its ID.

Type

Service!

Arguments
Name Description
id - ServiceID!
Example

loadSocketFromID

Description

Load a Socket from its ID.

Type

Socket!

Arguments
Name Description
id - SocketID!
Example

loadTerminalFromID

Description

Load a Terminal from its ID.

Type

Terminal!

Arguments
Name Description
id - TerminalID!
Example

loadTypeDefFromID

Description

Load a TypeDef from its ID.

Type

TypeDef!

Arguments
Name Description
id - TypeDefID!
Example

module

Description

Create a new module.

Type

Module!

Example

moduleDependency

Description

Create a new module dependency configuration from a module source and name

Arguments
Name Description
name - String If set, the name to use for the dependency. Otherwise, once installed to a parent module, the name of the dependency module will be used by default. Default = ""
source - ModuleSourceID! The source of the dependency
Example

moduleSource

Description

Create a new module source instance from a source ref string.

Arguments
Name Description
refString - String! The string ref representation of the module source
stable - Boolean If true, enforce that the source is a stable version for source kinds that support versioning. Default = false
Example

pipeline

Description

Creates a named sub-pipeline.

Type

Query!

Arguments
Name Description
description - String Description of the sub-pipeline. Default = ""
labels - [PipelineLabel!] Labels to apply to the sub-pipeline.
name - String! Name of the sub-pipeline.
Example
query {
  pipeline(name: "build", description: "Builds the app container") {
    container {
      id
    }
  }
}

Try it in the API Playground!

secret

Description

Reference a secret by name.

Type

Secret!

Arguments
Name Description
accessor - String
name - String!
Example
query {
  secret(id: "eyJob3N0X2VudiI6IkhPTUUifQ==") {
    plaintext
  }
}

Try it in the API Playground!

setSecret

Description

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

The plaintext value is limited to a size of 128000 bytes.

Type

Secret!

Arguments
Name Description
name - String! The user defined name for this secret
plaintext - String! The plaintext of the secret
Example

typeDef

Description

Create a new TypeDef.

Type

TypeDef!

Example

version

Description

Get the current Dagger Engine version.

Type

String!

Example

Types

Boolean

Description

The Boolean scalar type represents true or false.

BuildArg

Description

Key value object that represents a build argument.

Fields
Input Field Description
name - String! The build argument name.
value - String! The build argument value.
Example
{
  "name": "xyz789",
  "value": "abc123"
}

CacheSharingMode

Description

Sharing mode of the cache volume.

Values
Enum Value Description

SHARED

Shares the cache volume amongst many build pipelines

PRIVATE

Keeps a cache volume for a single build pipeline

LOCKED

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

CacheVolume

Description

A directory whose contents persist across runs.

Fields
Field Name Description
id - CacheVolumeID! A unique identifier for this CacheVolume.

CacheVolumeID

Description

The CacheVolumeID scalar type represents an identifier for an object of type CacheVolume.

Container

Description

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

Fields
Field Name Description
asService - Service!

Turn the container into a Service.

Be sure to set any exposed ports before this conversion.

asTarball - File! Returns a File representing the container serialized to a tarball.
Arguments
forcedCompression - ImageLayerCompression

Force each layer of the 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.

mediaTypes - ImageMediaTypes

Use the specified media types for the image's layers.

Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

platformVariants - [ContainerID!]

Identifiers for other platform specific containers.

Used for multi-platform images.

build - Container! Initializes this container from a Dockerfile build.
Arguments
buildArgs - [BuildArg!]

Additional build arguments.

context - DirectoryID!

Directory context used by the Dockerfile.

dockerfile - String

Path to the Dockerfile to use.

secrets - [SecretID!]

Secrets to pass to the build.

They will be mounted at /run/secrets/[secret-name] in the build container

They can be accessed in the Dockerfile using the "secret" mount type and mount path /run/secrets/[secret-name], e.g. RUN --mount=type=secret,id=my-secret curl [http://example.com?token=$(cat /run/secrets/my-secret)](http://example.com?token=$(cat /run/secrets/my-secret))

target - String

Target build stage to build.

defaultArgs - [String!]! Retrieves default arguments for future commands.
directory - Directory!

Retrieves a directory at the given path.

Mounts are included.

Arguments
path - String!

The path of the directory to retrieve (e.g., "./src").

entrypoint - [String!]! Retrieves entrypoint to be prepended to the arguments of all commands.
envVariable - String Retrieves the value of the specified environment variable.
Arguments
name - String!

The name of the environment variable to retrieve (e.g., "PATH").

envVariables - [EnvVariable!]! Retrieves the list of environment variables passed to commands.
experimentalWithAllGPUs - Container!

EXPERIMENTAL API! Subject to change/removal at any time.

Configures all available GPUs on the host to be accessible to this container.

This currently works for Nvidia devices only.

experimentalWithGPU - Container!

EXPERIMENTAL API! Subject to change/removal at any time.

Configures the provided list of devices to be accessible to this container.

This currently works for Nvidia devices only.

Arguments
devices - [String!]!

List of devices to be accessible to this container.

export - String!

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

It can also export platform variants.

Arguments
forcedCompression - ImageLayerCompression

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.

mediaTypes - ImageMediaTypes

Use the specified media types for the exported image's layers.

Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

path - String!

Host's destination path (e.g., "./tarball").

Path can be relative to the engine's workdir or absolute.

platformVariants - [ContainerID!]

Identifiers for other platform specific containers.

Used for multi-platform image.

exposedPorts - [Port!]!

Retrieves the list of exposed ports.

This includes ports already exposed by the image, even if not explicitly added with dagger.

file - File!

Retrieves a file at the given path.

Mounts are included.

Arguments
path - String!

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

from - Container! Initializes this container from a pulled base image.
Arguments
address - String!

Image's address from its registry.

Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").

id - ContainerID! A unique identifier for this Container.
imageRef - String! The unique image reference which can only be retrieved immediately after the 'Container.From' call.
import - Container! Reads the container from an OCI tarball.
Arguments
source - FileID!

File to read the container from.

tag - String

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

label - String Retrieves the value of the specified label.
Arguments
name - String!

The name of the label (e.g., "org.opencontainers.artifact.created").

labels - [Label!]! Retrieves the list of labels passed to container.
mounts - [String!]! Retrieves the list of paths where a directory is mounted.
pipeline - Container! Creates a named sub-pipeline.
Arguments
description - String

Description of the sub-pipeline.

labels - [PipelineLabel!]

Labels to apply to the sub-pipeline.

name - String!

Name of the sub-pipeline.

platform - Platform! The platform this container executes and publishes as.
publish - String!

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

Publish returns a fully qualified ref.

It can also publish platform variants.

Arguments
address - String!

Registry's address to publish the image to.

Formatted as [host]/[user]/[repo]:[tag] (e.g. "docker.io/dagger/dagger:main").

forcedCompression - ImageLayerCompression

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.

mediaTypes - ImageMediaTypes

Use the specified media types for the published image's layers.

Defaults to OCI, which is largely compatible with most recent registries, but Docker may be needed for older registries without OCI support.

platformVariants - [ContainerID!]

Identifiers for other platform specific containers.

Used for multi-platform image.

rootfs - Directory! Retrieves this container's root filesystem. Mounts are not included.
stderr - String!

The error stream of the last executed command.

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

stdout - String!

The output stream of the last executed command.

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

sync - ContainerID!

Forces evaluation of the pipeline in the engine.

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

terminal - Container! Opens an interactive terminal for this container using its configured default terminal command if not overridden by args (or sh as a fallback default).
Arguments
cmd - [String!]

If set, override the container's default terminal command and invoke these command arguments instead.

experimentalPrivilegedNesting - Boolean

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.

insecureRootCapabilities - Boolean

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.

user - String! Retrieves the user to be set for all commands.
withDefaultArgs - Container! Configures default arguments for future commands.
Arguments
args - [String!]!

Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).

withDefaultTerminalCmd - Container! Set the default command to invoke for the container's terminal API.
Arguments
args - [String!]!

The args of the command.

experimentalPrivilegedNesting - Boolean

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.

insecureRootCapabilities - Boolean

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.

withDirectory - Container! Retrieves this container plus a directory written at the given path.
Arguments
directory - DirectoryID!

Identifier of the directory to write

exclude - [String!]

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

include - [String!]

Patterns to include in the written directory (e.g. ["*.go", "go.mod", "go.sum"]).

owner - String

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.

path - String!

Location of the written directory (e.g., "/tmp/directory").

withEntrypoint - Container! Retrieves this container but with a different command entrypoint.
Arguments
args - [String!]!

Entrypoint to use for future executions (e.g., ["go", "run"]).

keepDefaultArgs - Boolean

Don't remove the default arguments when setting the entrypoint.

withEnvVariable - Container! Retrieves this container plus the given environment variable.
Arguments
expand - Boolean

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

name - String!

The name of the environment variable (e.g., "HOST").

value - String!

The value of the environment variable. (e.g., "localhost").

withExec - Container! Retrieves this container after executing the specified command inside it.
Arguments
args - [String!]!

Command to run instead of the container's default command (e.g., ["run", "main.go"]).

If empty, the container's default command is used.

experimentalPrivilegedNesting - Boolean

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.

insecureRootCapabilities - Boolean

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.

redirectStderr - String

Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").

redirectStdout - String

Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").

skipEntrypoint - Boolean

DEPRECATED: For true this can be removed. For false, use useEntrypoint instead.

stdin - String

Content to write to the command's standard input before closing (e.g., "Hello world").

useEntrypoint - Boolean

If the container has an entrypoint, prepend it to the args.

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

Arguments
description - String

Optional port description

experimentalSkipHealthcheck - Boolean

Skip the health check when run as a service.

port - Int!

Port number to expose

protocol - NetworkProtocol

Transport layer network protocol

withFile - Container! Retrieves this container plus the contents of the given file copied to the given path.
Arguments
owner - String

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.

path - String!

Location of the copied file (e.g., "/tmp/file.txt").

permissions - Int

Permission given to the copied file (e.g., 0600).

source - FileID!

Identifier of the file to copy.

withFiles - Container! Retrieves this container plus the contents of the given files copied to the given path.
Arguments
owner - String

A user:group to set for the files.

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.

path - String!

Location where copied files should be placed (e.g., "/src").

permissions - Int

Permission given to the copied files (e.g., 0600).

sources - [FileID!]!

Identifiers of the files to copy.

withFocus - Container! Indicate that subsequent operations should be featured more prominently in the UI.
withLabel - Container! Retrieves this container plus the given label.
Arguments
name - String!

The name of the label (e.g., "org.opencontainers.artifact.created").

value - String!

The value of the label (e.g., "2023-01-01T00:00:00Z").

withMountedCache - Container! Retrieves this container plus a cache volume mounted at the given path.
Arguments
cache - CacheVolumeID!

Identifier of the cache volume to mount.

owner - String

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.

path - String!

Location of the cache directory (e.g., "/cache/node_modules").

sharing - CacheSharingMode

Sharing mode of the cache volume.

source - DirectoryID

Identifier of the directory to use as the cache volume's root.

withMountedDirectory - Container! Retrieves this container plus a directory mounted at the given path.
Arguments
owner - String

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.

path - String!

Location of the mounted directory (e.g., "/mnt/directory").

source - DirectoryID!

Identifier of the mounted directory.

withMountedFile - Container! Retrieves this container plus a file mounted at the given path.
Arguments
owner - String

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.

path - String!

Location of the mounted file (e.g., "/tmp/file.txt").

source - FileID!

Identifier of the mounted file.

withMountedSecret - Container! Retrieves this container plus a secret mounted into a file at the given path.
Arguments
mode - Int

Permission given to the mounted secret (e.g., 0600).

This option requires an owner to be set to be active.

owner - String

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.

path - String!

Location of the secret file (e.g., "/tmp/secret.txt").

source - SecretID!

Identifier of the secret to mount.

withMountedTemp - Container! Retrieves this container plus a temporary directory mounted at the given path. Any writes will be ephemeral to a single withExec call; they will not be persisted to subsequent withExecs.
Arguments
path - String!

Location of the temporary directory (e.g., "/tmp/temp_dir").

withNewFile - Container! Retrieves this container plus a new file written at the given path.
Arguments
contents - String!

Content of the file to write (e.g., "Hello world!").

owner - String

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.

path - String!

Location of the written file (e.g., "/tmp/file.txt").

permissions - Int

Permission given to the written file (e.g., 0600).

withoutDefaultArgs - Container! Retrieves this container with unset default arguments for future commands.
withoutDirectory - Container! Retrieves this container with the directory at the given path removed.
Arguments
path - String!

Location of the directory to remove (e.g., ".github/").

withoutEntrypoint - Container! Retrieves this container with an unset command entrypoint.
Arguments
keepDefaultArgs - Boolean

Don't remove the default arguments when unsetting the entrypoint.

withoutEnvVariable - Container! Retrieves this container minus the given environment variable.
Arguments
name - String!

The name of the environment variable (e.g., "HOST").

withoutExposedPort - Container! Unexpose a previously exposed port.
Arguments
port - Int!

Port number to unexpose

protocol - NetworkProtocol

Port protocol to unexpose

withoutFile - Container! Retrieves this container with the file at the given path removed.
Arguments
path - String!

Location of the file to remove (e.g., "/file.txt").

withoutFocus - Container!

Indicate that subsequent operations should not be featured more prominently in the UI.

This is the initial state of all containers.

withoutLabel - Container! Retrieves this container minus the given environment label.
Arguments
name - String!

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

withoutMount - Container! Retrieves this container after unmounting everything at the given path.
Arguments
path - String!

Location of the cache directory (e.g., "/cache/node_modules").

withoutRegistryAuth - Container! Retrieves this container without the registry authentication of a given address.
Arguments
address - String!

Registry's address to remove the authentication from.

Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

withoutSecretVariable - Container! Retrieves this container minus the given environment variable containing the secret.
Arguments
name - String!

The name of the environment variable (e.g., "HOST").

withoutUnixSocket - Container! Retrieves this container with a previously added Unix socket removed.
Arguments
path - String!

Location of the socket to remove (e.g., "/tmp/socket").

withoutUser - Container!

Retrieves this container with an unset command user.

Should default to root.

withoutWorkdir - Container!

Retrieves this container with an unset working directory.

Should default to "/".

withRegistryAuth - Container! Retrieves this container with a registry authentication for a given address.
Arguments
address - String!

Registry's address to bind the authentication to.

Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

secret - SecretID!

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

username - String!

The username of the registry's account (e.g., "Dagger").

withRootfs - Container! Retrieves the container with the given directory mounted to /.
Arguments
directory - DirectoryID!

Directory to mount.

withSecretVariable - Container! Retrieves this container plus an env variable containing the given secret.
Arguments
name - String!

The name of the secret variable (e.g., "API_SECRET").

secret - SecretID!

The identifier of the secret value.

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

Arguments
alias - String!

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

service - ServiceID!

Identifier of the service container

withUnixSocket - Container! Retrieves this container plus a socket forwarded to the given Unix socket path.
Arguments
owner - String

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.

path - String!

Location of the forwarded Unix socket (e.g., "/tmp/socket").

source - SocketID!

Identifier of the socket to forward.

withUser - Container! Retrieves this container with a different command user.
Arguments
name - String!

The user to set (e.g., "root").

withWorkdir - Container! Retrieves this container with a different working directory.
Arguments
path - String!

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

workdir - String! Retrieves the working directory for all commands.

ContainerID

Description

The ContainerID scalar type represents an identifier for an object of type Container.

CurrentModule

Description

Reflective module API provided to functions at runtime.

Fields
Field Name Description
id - CurrentModuleID! A unique identifier for this CurrentModule.
name - String! The name of the module being executed in
source - Directory! The directory containing the module's source code loaded into the engine (plus any generated code that may have been created).
workdir - Directory! Load a directory from the module's scratch working directory, including any changes that may have been made to it during module function execution.
Arguments
exclude - [String!]

Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).

include - [String!]

Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).

path - String!

Location of the directory to access (e.g., ".").

workdirFile - File! Load a file from the module's scratch working directory, including any changes that may have been made to it during module function execution.Load a file from the module's scratch working directory, including any changes that may have been made to it during module function execution.
Arguments
path - String!

Location of the file to retrieve (e.g., "README.md").

CurrentModuleID

Description

The CurrentModuleID scalar type represents an identifier for an object of type CurrentModule.

DaggerEngine

Description

The Dagger engine configuration and state

Fields
Field Name Description
id - DaggerEngineID! A unique identifier for this DaggerEngine.
localCache - DaggerEngineCache! The local (on-disk) cache for the Dagger engine

DaggerEngineCache

Description

A cache storage for the Dagger engine

Fields
Field Name Description
entrySet - DaggerEngineCacheEntrySet! The current set of entries in the cache
id - DaggerEngineCacheID! A unique identifier for this DaggerEngineCache.
keepBytes - Int! The maximum bytes to keep in the cache without pruning, after which automatic pruning may kick in.
prune - Void Prune the cache of releaseable entries

DaggerEngineCacheEntry

Description

An individual cache entry in a cache entry set

Fields
Field Name Description
activelyUsed - Boolean! Whether the cache entry is actively being used.
createdTimeUnixNano - Int! The time the cache entry was created, in Unix nanoseconds.
description - String! The description of the cache entry.
diskSpaceBytes - Int! The disk space used by the cache entry.
id - DaggerEngineCacheEntryID! A unique identifier for this DaggerEngineCacheEntry.
mostRecentUseTimeUnixNano - Int! The most recent time the cache entry was used, in Unix nanoseconds.

DaggerEngineCacheEntryID

Description

The DaggerEngineCacheEntryID scalar type represents an identifier for an object of type DaggerEngineCacheEntry.

DaggerEngineCacheEntrySet

Description

A set of cache entries returned by a query to a cache

Fields
Field Name Description
diskSpaceBytes - Int! The total disk space used by the cache entries in this set.
entries - [DaggerEngineCacheEntry!]! The list of individual cache entries in the set
entryCount - Int! The number of cache entries in this set.
id - DaggerEngineCacheEntrySetID! A unique identifier for this DaggerEngineCacheEntrySet.

DaggerEngineCacheEntrySetID

Description

The DaggerEngineCacheEntrySetID scalar type represents an identifier for an object of type DaggerEngineCacheEntrySet.

DaggerEngineCacheID

Description

The DaggerEngineCacheID scalar type represents an identifier for an object of type DaggerEngineCache.

DaggerEngineID

Description

The DaggerEngineID scalar type represents an identifier for an object of type DaggerEngine.

Directory

Description

A directory.

Fields
Field Name Description
asModule - Module! Load the directory as a Dagger module
Arguments
engineVersion - String

The engine version to upgrade to.

sourceRootPath - String

An optional subpath of the directory which contains the module's configuration file.

This is needed when the module code is in a subdirectory but requires parent directories to be loaded in order to execute. For example, the module source code may need a go.mod, project.toml, package.json, etc. file from a parent directory.

If not set, the module source code is loaded from the root of the directory.

diff - Directory! Gets the difference between this directory and an another directory.
Arguments
other - DirectoryID!

Identifier of the directory to compare.

directory - Directory! Retrieves a directory at the given path.
Arguments
path - String!

Location of the directory to retrieve (e.g., "/src").

dockerBuild - Container! Builds a new Docker container from this directory.
Arguments
buildArgs - [BuildArg!]

Build arguments to use in the build.

dockerfile - String

Path to the Dockerfile to use (e.g., "frontend.Dockerfile").

platform - Platform

The platform to build.

secrets - [SecretID!]

Secrets to pass to the build.

They will be mounted at /run/secrets/[secret-name].

target - String

Target build stage to build.

entries - [String!]! Returns a list of files and directories at the given path.
Arguments
path - String

Location of the directory to look at (e.g., "/src").

export - String! Writes the contents of the directory to a path on the host.
Arguments
path - String!

Location of the copied directory (e.g., "logs/").

wipe - Boolean

If true, then the host directory will be wiped clean before exporting so that it exactly matches the directory being exported; this means it will delete any files on the host that aren't in the exported dir. If false (the default), the contents of the directory will be merged with any existing contents of the host directory, leaving any existing files on the host that aren't in the exported directory alone.

file - File! Retrieves a file at the given path.
Arguments
path - String!

Location of the file to retrieve (e.g., "README.md").

glob - [String!]! Returns a list of files and directories that matche the given pattern.
Arguments
pattern - String!

Pattern to match (e.g., "*.md").

id - DirectoryID! A unique identifier for this Directory.
pipeline - Directory! Creates a named sub-pipeline.
Arguments
description - String

Description of the sub-pipeline.

labels - [PipelineLabel!]

Labels to apply to the sub-pipeline.

name - String!

Name of the sub-pipeline.

sync - DirectoryID! Force evaluation in the engine.
terminal - Directory! Opens an interactive terminal in new container with this directory mounted inside.
Arguments
cmd - [String!]

If set, override the container's default terminal command and invoke these command arguments instead.

container - ContainerID

If set, override the default container used for the terminal.

experimentalPrivilegedNesting - Boolean

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.

insecureRootCapabilities - Boolean

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.

withDirectory - Directory! Retrieves this directory plus a directory written at the given path.
Arguments
directory - DirectoryID!

Identifier of the directory to copy.

exclude - [String!]

Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).

include - [String!]

Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).

path - String!

Location of the written directory (e.g., "/src/").

withFile - Directory! Retrieves this directory plus the contents of the given file copied to the given path.
Arguments
path - String!

Location of the copied file (e.g., "/file.txt").

permissions - Int

Permission given to the copied file (e.g., 0600).

source - FileID!

Identifier of the file to copy.

withFiles - Directory! Retrieves this directory plus the contents of the given files copied to the given path.
Arguments
path - String!

Location where copied files should be placed (e.g., "/src").

permissions - Int

Permission given to the copied files (e.g., 0600).

sources - [FileID!]!

Identifiers of the files to copy.

withNewDirectory - Directory! Retrieves this directory plus a new directory created at the given path.
Arguments
path - String!

Location of the directory created (e.g., "/logs").

permissions - Int

Permission granted to the created directory (e.g., 0777).

withNewFile - Directory! Retrieves this directory plus a new file written at the given path.
Arguments
contents - String!

Content of the written file (e.g., "Hello world!").

path - String!

Location of the written file (e.g., "/file.txt").

permissions - Int

Permission given to the copied file (e.g., 0600).

withoutDirectory - Directory! Retrieves this directory with the directory at the given path removed.
Arguments
path - String!

Location of the directory to remove (e.g., ".github/").

withoutFile - Directory! Retrieves this directory with the file at the given path removed.
Arguments
path - String!

Location of the file to remove (e.g., "/file.txt").

withTimestamps - Directory! Retrieves this directory with all file/dir timestamps set to the given time.
Arguments
timestamp - Int!

Timestamp to set dir/files in.

Formatted in seconds following Unix epoch (e.g., 1672531199).

DirectoryID

Description

The DirectoryID scalar type represents an identifier for an object of type Directory.

EnumTypeDef

Description

A definition of a custom enum defined in a Module.

Fields
Field Name Description
description - String! A doc string for the enum, if any.
id - EnumTypeDefID! A unique identifier for this EnumTypeDef.
name - String! The name of the enum.
sourceModuleName - String! If this EnumTypeDef is associated with a Module, the name of the module. Unset otherwise.
values - [EnumValueTypeDef!]! The values of the enum.

EnumTypeDefID

Description

The EnumTypeDefID scalar type represents an identifier for an object of type EnumTypeDef.

EnumValueTypeDef

Description

A definition of a value in a custom enum defined in a Module.

Fields
Field Name Description
description - String! A doc string for the enum value, if any.
id - EnumValueTypeDefID! A unique identifier for this EnumValueTypeDef.
name - String! The name of the enum value.

EnumValueTypeDefID

Description

The EnumValueTypeDefID scalar type represents an identifier for an object of type EnumValueTypeDef.

EnvVariable

Description

An environment variable name and value.

Fields
Field Name Description
id - EnvVariableID! A unique identifier for this EnvVariable.
name - String! The environment variable name.
value - String! The environment variable value.

EnvVariableID

Description

The EnvVariableID scalar type represents an identifier for an object of type EnvVariable.

FieldTypeDef

Description

A definition of a field on a custom object defined in a Module.

A field on an object has a static value, as opposed to a function on an object whose value is computed by invoking code (and can accept arguments).

Fields
Field Name Description
description - String! A doc string for the field, if any.
id - FieldTypeDefID! A unique identifier for this FieldTypeDef.
name - String! The name of the field in lowerCamelCase format.
typeDef - TypeDef! The type of the field.

FieldTypeDefID

Description

The FieldTypeDefID scalar type represents an identifier for an object of type FieldTypeDef.

File

Description

A file.

Fields
Field Name Description
contents - String! Retrieves the contents of the file.
export - String! Writes the file to a file path on the host.
Arguments
allowParentDirPath - Boolean

If allowParentDirPath is true, the path argument can be a directory path, in which case the file will be created in that directory.

path - String!

Location of the written directory (e.g., "output.txt").

id - FileID! A unique identifier for this File.
name - String! Retrieves the name of the file.
size - Int! Retrieves the size of the file, in bytes.
sync - FileID! Force evaluation in the engine.
withName - File! Retrieves this file with its name set to the given name.
Arguments
name - String!

Name to set file to.

withTimestamps - File! Retrieves this file with its created/modified timestamps set to the given time.
Arguments
timestamp - Int!

Timestamp to set dir/files in.

Formatted in seconds following Unix epoch (e.g., 1672531199).

FileID

Description

The FileID scalar type represents an identifier for an object of type File.

Function

Description

Function represents a resolver provided by a Module.

A function always evaluates against a parent object and is given a set of named arguments.

Fields
Field Name Description
args - [FunctionArg!]! Arguments accepted by the function, if any.
description - String! A doc string for the function, if any.
id - FunctionID! A unique identifier for this Function.
name - String! The name of the function.
returnType - TypeDef! The type returned by the function.
withArg - Function! Returns the function with the provided argument
Arguments
defaultValue - JSON

A default value to use for this argument if not explicitly set by the caller, if any

description - String

A doc string for the argument, if any

name - String!

The name of the argument

typeDef - TypeDefID!

The type of the argument

withDescription - Function! Returns the function with the given doc string.
Arguments
description - String!

The doc string to set.

FunctionArg

Description

An argument accepted by a function.

This is a specification for an argument at function definition time, not an argument passed at function call time.

Fields
Field Name Description
defaultValue - JSON! A default value to use for this argument when not explicitly set by the caller, if any.
description - String! A doc string for the argument, if any.
id - FunctionArgID! A unique identifier for this FunctionArg.
name - String! The name of the argument in lowerCamelCase format.
typeDef - TypeDef! The type of the argument.

FunctionArgID

Description

The FunctionArgID scalar type represents an identifier for an object of type FunctionArg.

FunctionCall

Description

An active function call.

Fields
Field Name Description
id - FunctionCallID! A unique identifier for this FunctionCall.
inputArgs - [FunctionCallArgValue!]! The argument values the function is being invoked with.
name - String! The name of the function being called.
parent - JSON! The value of the parent object of the function being called. If the function is top-level to the module, this is always an empty object.
parentName - String! The name of the parent object of the function being called. If the function is top-level to the module, this is the name of the module.
returnValue - Void Set the return value of the function call to the provided value.
Arguments
value - JSON!

JSON serialization of the return value.

FunctionCallArgValue

Description

A value passed as a named argument to a function call.

Fields
Field Name Description
id - FunctionCallArgValueID! A unique identifier for this FunctionCallArgValue.
name - String! The name of the argument.
value - JSON! The value of the argument represented as a JSON serialized string.

FunctionCallArgValueID

Description

The FunctionCallArgValueID scalar type represents an identifier for an object of type FunctionCallArgValue.

FunctionCallID

Description

The FunctionCallID scalar type represents an identifier for an object of type FunctionCall.

FunctionID

Description

The FunctionID scalar type represents an identifier for an object of type Function.

GeneratedCode

Description

The result of running an SDK's codegen.

Fields
Field Name Description
code - Directory! The directory containing the generated code.
id - GeneratedCodeID! A unique identifier for this GeneratedCode.
vcsGeneratedPaths - [String!]! List of paths to mark generated in version control (i.e. .gitattributes).
vcsIgnoredPaths - [String!]! List of paths to ignore in version control (i.e. .gitignore).
withVCSGeneratedPaths - GeneratedCode! Set the list of paths to mark generated in version control.
Arguments
paths - [String!]!
withVCSIgnoredPaths - GeneratedCode! Set the list of paths to ignore in version control.
Arguments
paths - [String!]!

GeneratedCodeID

Description

The GeneratedCodeID scalar type represents an identifier for an object of type GeneratedCode.

GitModuleSource

Description

Module source originating from a git repo.

Fields
Field Name Description
cloneURL - String! The URL to clone the root of the git repo from
commit - String! The resolved commit of the git repo this source points to.
contextDirectory - Directory! The directory containing everything needed to load load and use the module.
htmlURL - String! The URL to the source's git repo in a web browser
id - GitModuleSourceID! A unique identifier for this GitModuleSource.
root - String! The clean module name of the root of the module
rootSubpath - String! The path to the root of the module source under the context directory. This directory contains its configuration file. It also contains its source code (possibly as a subdirectory).
version - String! The specified version of the git repo this source points to.

GitModuleSourceID

Description

The GitModuleSourceID scalar type represents an identifier for an object of type GitModuleSource.

GitRef

Description

A git ref (tag, branch, or commit).

Fields
Field Name Description
commit - String! The resolved commit id at this ref.
id - GitRefID! A unique identifier for this GitRef.
tree - Directory! The filesystem tree at this ref.

GitRefID

Description

The GitRefID scalar type represents an identifier for an object of type GitRef.

GitRepository

Description

A git repository.

Fields
Field Name Description
branch - GitRef! Returns details of a branch.
Arguments
name - String!

Branch's name (e.g., "main").

commit - GitRef! Returns details of a commit.
Arguments
id - String!

Identifier of the commit (e.g., "b6315d8f2810962c601af73f86831f6866ea798b").

head - GitRef! Returns details for HEAD.
id - GitRepositoryID! A unique identifier for this GitRepository.
ref - GitRef! Returns details of a ref.
Arguments
name - String!

Ref's name (can be a commit identifier, a tag name, a branch name, or a fully-qualified ref).

tag - GitRef! Returns details of a tag.
Arguments
name - String!

Tag's name (e.g., "v0.3.9").

tags - [String!]! tags that match any of the given glob patterns.
Arguments
patterns - [String!]

Glob patterns (e.g., "refs/tags/v*").

withAuthHeader - GitRepository! Header to authenticate the remote with.
Arguments
header - SecretID!

Secret used to populate the Authorization HTTP header

withAuthToken - GitRepository! Token to authenticate the remote with.
Arguments
token - SecretID!

Secret used to populate the password during basic HTTP Authorization

GitRepositoryID

Description

The GitRepositoryID scalar type represents an identifier for an object of type GitRepository.

Host

Description

Information about the host environment.

Fields
Field Name Description
directory - Directory! Accesses a directory on the host.
Arguments
exclude - [String!]

Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).

include - [String!]

Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).

path - String!

Location of the directory to access (e.g., ".").

file - File! Accesses a file on the host.
Arguments
path - String!

Location of the file to retrieve (e.g., "README.md").

id - HostID! A unique identifier for this Host.
service - Service! Creates a service that forwards traffic to a specified address via the host.
Arguments
host - String

Upstream host to forward traffic to.

ports - [PortForward!]!

Ports to expose via the service, forwarding through the host network.

If a port's frontend is unspecified or 0, it defaults to the same as the backend port.

An empty set of ports is not valid; an error will be returned.

setSecretFile - Secret!

Sets a secret given a user-defined name and the file path on the host, and returns the secret.

The file is limited to a size of 512000 bytes.

Arguments
name - String!

The user defined name for this secret.

path - String!

Location of the file to set as a secret.

tunnel - Service! Creates a tunnel that forwards traffic from the host to a service.
Arguments
native - Boolean

Map each service port to the same port on the host, as if the service were running natively.

Note: enabling may result in port conflicts.

ports - [PortForward!]

Configure explicit port forwarding rules for the tunnel.

If a port's frontend is unspecified or 0, a random port will be chosen by the host.

If no ports are given, all of the service's ports are forwarded. If native is true, each port maps to the same port on the host. If native is false, each port maps to a random port chosen by the host.

If ports are given and native is true, the ports are additive.

service - ServiceID!

Service to send traffic from the tunnel.

unixSocket - Socket! Accesses a Unix socket on the host.
Arguments
path - String!

Location of the Unix socket (e.g., "/var/run/docker.sock").

HostID

Description

The HostID scalar type represents an identifier for an object of type Host.

ImageLayerCompression

Description

Compression algorithm to use for image layers.

Values
Enum Value Description

Gzip

Zstd

EStarGZ

Uncompressed

Example
"Gzip"

ImageMediaTypes

Description

Mediatypes to use in published or exported image metadata.

Values
Enum Value Description

OCIMediaTypes

DockerMediaTypes

Example
"OCIMediaTypes"

InputTypeDef

Description

A graphql input type, which is essentially just a group of named args. This is currently only used to represent pre-existing usage of graphql input types in the core API. It is not used by user modules and shouldn't ever be as user module accept input objects via their id rather than graphql input types.

Fields
Field Name Description
fields - [FieldTypeDef!]! Static fields defined on this input object, if any.
id - InputTypeDefID! A unique identifier for this InputTypeDef.
name - String! The name of the input object.

InputTypeDefID

Description

The InputTypeDefID scalar type represents an identifier for an object of type InputTypeDef.

Int

Description

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

InterfaceTypeDef

Description

A definition of a custom interface defined in a Module.

Fields
Field Name Description
description - String! The doc string for the interface, if any.
functions - [Function!]! Functions defined on this interface, if any.
id - InterfaceTypeDefID! A unique identifier for this InterfaceTypeDef.
name - String! The name of the interface.
sourceModuleName - String! If this InterfaceTypeDef is associated with a Module, the name of the module. Unset otherwise.

InterfaceTypeDefID

Description

The InterfaceTypeDefID scalar type represents an identifier for an object of type InterfaceTypeDef.

JSON

Description

An arbitrary JSON-encoded value.

Label

Description

A simple key value object that represents a label.

Fields
Field Name Description
id - LabelID! A unique identifier for this Label.
name - String! The label name.
value - String! The label value.

LabelID

Description

The LabelID scalar type represents an identifier for an object of type Label.

ListTypeDef

Description

A definition of a list type in a Module.

Fields
Field Name Description
elementTypeDef - TypeDef! The type of the elements in the list.
id - ListTypeDefID! A unique identifier for this ListTypeDef.

ListTypeDefID

Description

The ListTypeDefID scalar type represents an identifier for an object of type ListTypeDef.

LocalModuleSource

Description

Module source that that originates from a path locally relative to an arbitrary directory.

Fields
Field Name Description
contextDirectory - Directory The directory containing everything needed to load load and use the module.
id - LocalModuleSourceID! A unique identifier for this LocalModuleSource.
rootSubpath - String! The path to the root of the module source under the context directory. This directory contains its configuration file. It also contains its source code (possibly as a subdirectory).

LocalModuleSourceID

Description

The LocalModuleSourceID scalar type represents an identifier for an object of type LocalModuleSource.

Module

Description

A Dagger module.

Fields
Field Name Description
dependencies - [Module!]! Modules used by this module.
dependencyConfig - [ModuleDependency!]! The dependencies as configured by the module.
description - String! The doc string of the module, if any
enums - [TypeDef!]! Enumerations served by this module.
generatedContextDiff - Directory! The generated files and directories made on top of the module source's context directory.
generatedContextDirectory - Directory! The module source's context plus any configuration and source files created by codegen.
id - ModuleID! A unique identifier for this Module.
initialize - Module! Retrieves the module with the objects loaded via its SDK.
interfaces - [TypeDef!]! Interfaces served by this module.
name - String! The name of the module
objects - [TypeDef!]! Objects served by this module.
runtime - Container! The container that runs the module's entrypoint. It will fail to execute if the module doesn't compile.
sdk - String! The SDK used by this module. Either a name of a builtin SDK or a module source ref string pointing to the SDK's implementation.
serve - Void

Serve a module's API in the current session.

Note: this can only be called once per session. In the future, it could return a stream or service to remove the side effect.

source - ModuleSource! The source for the module.
withDescription - Module! Retrieves the module with the given description
Arguments
description - String!

The description to set

withEnum - Module! This module plus the given Enum type and associated values
Arguments
enum - TypeDefID!
withInterface - Module! This module plus the given Interface type and associated functions
Arguments
iface - TypeDefID!
withObject - Module! This module plus the given Object type and associated functions.
Arguments
object - TypeDefID!
withSource - Module! Retrieves the module with basic configuration loaded if present.
Arguments
engineVersion - String

The engine version to upgrade to.

source - ModuleSourceID!

The module source to initialize from.

ModuleDependency

Description

The configuration of dependency of a module.

Fields
Field Name Description
id - ModuleDependencyID! A unique identifier for this ModuleDependency.
name - String! The name of the dependency module.
source - ModuleSource! The source for the dependency module.

ModuleDependencyID

Description

The ModuleDependencyID scalar type represents an identifier for an object of type ModuleDependency.

ModuleID

Description

The ModuleID scalar type represents an identifier for an object of type Module.

ModuleSource

Description

The source needed to load and run a module, along with any metadata about the source such as versions/urls/etc.

Fields
Field Name Description
asGitSource - GitModuleSource If the source is a of kind git, the git source representation of it.
asLocalSource - LocalModuleSource If the source is of kind local, the local source representation of it.
asModule - Module! Load the source as a module. If this is a local source, the parent directory must have been provided during module source creation
Arguments
engineVersion - String

The engine version to upgrade to.

asString - String! A human readable ref string representation of this module source.
configExists - Boolean! Returns whether the module source has a configuration file.
contextDirectory - Directory! The directory containing everything needed to load load and use the module.
dependencies - [ModuleDependency!]! The dependencies of the module source. Includes dependencies from the configuration and any extras from withDependencies calls.
directory - Directory! The directory containing the module configuration and source code (source code may be in a subdir).
Arguments
path - String!

The path from the source directory to select.

id - ModuleSourceID! A unique identifier for this ModuleSource.
kind - ModuleSourceKind! The kind of source (e.g. local, git, etc.)
moduleName - String! If set, the name of the module this source references, including any overrides at runtime by callers.
moduleOriginalName - String! The original name of the module this source references, as defined in the module configuration.
resolveContextPathFromCaller - String! The path to the module source's context directory on the caller's filesystem. Only valid for local sources.
resolveDependency - ModuleSource! Resolve the provided module source arg as a dependency relative to this module source.
Arguments
dep - ModuleSourceID!

The dependency module source to resolve.

resolveDirectoryFromCaller - Directory! Load a directory from the caller optionally with a given view applied.
Arguments
path - String!

The path on the caller's filesystem to load.

viewName - String

If set, the name of the view to apply to the path.

resolveFromCaller - ModuleSource! Load the source from its path on the caller's filesystem, including only needed+configured files and directories. Only valid for local sources.
sourceRootSubpath - String! The path relative to context of the root of the module source, which contains dagger.json. It also contains the module implementation source code, but that may or may not being a subdir of this root.
sourceSubpath - String! The path relative to context of the module implementation source code.
view - ModuleSourceView! Retrieve a named view defined for this module source.
Arguments
name - String!

The name of the view to retrieve.

views - [ModuleSourceView!]! The named views defined for this module source, which are sets of directory filters that can be applied to directory arguments provided to functions.
withContextDirectory - ModuleSource! Update the module source with a new context directory. Only valid for local sources.
Arguments
dir - DirectoryID!

The directory to set as the context directory.

withDependencies - ModuleSource! Append the provided dependencies to the module source's dependency list.
Arguments
dependencies - [ModuleDependencyID!]!

The dependencies to append.

withName - ModuleSource! Update the module source with a new name.
Arguments
name - String!

The name to set.

withSDK - ModuleSource! Update the module source with a new SDK.
Arguments
sdk - String!

The SDK to set.

withSourceSubpath - ModuleSource! Update the module source with a new source subpath.
Arguments
path - String!

The path to set as the source subpath.

withView - ModuleSource! Update the module source with a new named view.
Arguments
name - String!

The name of the view to set.

patterns - [String!]!

The patterns to set as the view filters.

ModuleSourceID

Description

The ModuleSourceID scalar type represents an identifier for an object of type ModuleSource.

ModuleSourceKind

Description

The kind of module source.

Values
Enum Value Description

LOCAL_SOURCE

GIT_SOURCE

Example
"LOCAL_SOURCE"

ModuleSourceView

Description

A named set of path filters that can be applied to directory arguments provided to functions.

Fields
Field Name Description
id - ModuleSourceViewID! A unique identifier for this ModuleSourceView.
name - String! The name of the view
patterns - [String!]! The patterns of the view used to filter paths

ModuleSourceViewID

Description

The ModuleSourceViewID scalar type represents an identifier for an object of type ModuleSourceView.

NetworkProtocol

Description

Transport layer network protocol associated to a port.

Values
Enum Value Description

TCP

UDP

Example
"TCP"

ObjectTypeDef

Description

A definition of a custom object defined in a Module.

Fields
Field Name Description
constructor - Function The function used to construct new instances of this object, if any
description - String! The doc string for the object, if any.
fields - [FieldTypeDef!]! Static fields defined on this object, if any.
functions - [Function!]! Functions defined on this object, if any.
id - ObjectTypeDefID! A unique identifier for this ObjectTypeDef.
name - String! The name of the object.
sourceModuleName - String! If this ObjectTypeDef is associated with a Module, the name of the module. Unset otherwise.

ObjectTypeDefID

Description

The ObjectTypeDefID scalar type represents an identifier for an object of type ObjectTypeDef.

PipelineLabel

Description

Key value object that represents a pipeline label.

Fields
Input Field Description
name - String! Label name.
value - String! Label value.
Example
{
  "name": "abc123",
  "value": "abc123"
}

Platform

Description

The platform config OS and architecture in a Container.

The format is [os]/[platform]/[version] (e.g., "darwin/arm64/v7", "windows/amd64", "linux/arm64").

Port

Description

A port exposed by a container.

Fields
Field Name Description
description - String The port description.
experimentalSkipHealthcheck - Boolean! Skip the health check when run as a service.
id - PortID! A unique identifier for this Port.
port - Int! The port number.
protocol - NetworkProtocol! The transport layer protocol.

PortForward

Description

Port forwarding rules for tunneling network traffic.

Fields
Input Field Description
backend - Int! Destination port for traffic.
frontend - Int Port to expose to clients. If unspecified, a default will be chosen.
protocol - NetworkProtocol Transport layer protocol to use for traffic. Default = TCP
Example
{"backend": 987, "frontend": 123, "protocol": "TCP"}

PortID

Description

The PortID scalar type represents an identifier for an object of type Port.

ScalarTypeDef

Description

A definition of a custom scalar defined in a Module.

Fields
Field Name Description
description - String! A doc string for the scalar, if any.
id - ScalarTypeDefID! A unique identifier for this ScalarTypeDef.
name - String! The name of the scalar.
sourceModuleName - String! If this ScalarTypeDef is associated with a Module, the name of the module. Unset otherwise.

ScalarTypeDefID

Description

The ScalarTypeDefID scalar type represents an identifier for an object of type ScalarTypeDef.

Secret

Description

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

Fields
Field Name Description
id - SecretID! A unique identifier for this Secret.
name - String! The name of this secret.
plaintext - String! The value of this secret.

SecretID

Description

The SecretID scalar type represents an identifier for an object of type Secret.

Service

Description

A content-addressed service providing TCP connectivity.

Fields
Field Name Description
endpoint - String!

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.

Arguments
port - Int

The exposed port number for the endpoint

scheme - String

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

hostname - String! Retrieves a hostname which can be used by clients to reach this container.
id - ServiceID! A unique identifier for this Service.
ports - [Port!]! Retrieves the list of ports provided by the service.
start - ServiceID!

Start the service and wait for its health checks to succeed.

Services bound to a Container do not need to be manually started.

stop - ServiceID! Stop the service.
Arguments
kill - Boolean

Immediately kill the service without waiting for a graceful exit

up - Void Creates a tunnel that forwards traffic from the caller's network to this service.
Arguments
ports - [PortForward!]

List of frontend/backend port mappings to forward.

Frontend is the port accepting traffic on the host, backend is the service port.

random - Boolean

Bind each tunnel port to a random port on the host.

ServiceID

Description

The ServiceID scalar type represents an identifier for an object of type Service.

Socket

Description

A Unix or TCP/IP socket that can be mounted into a container.

Fields
Field Name Description
id - SocketID! A unique identifier for this Socket.

SocketID

Description

The SocketID scalar type represents an identifier for an object of type Socket.

String

Description

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.

Terminal

Description

An interactive terminal that clients can connect to.

Fields
Field Name Description
id - TerminalID! A unique identifier for this Terminal.
sync - TerminalID!

Forces evaluation of the pipeline in the engine.

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

TerminalID

Description

The TerminalID scalar type represents an identifier for an object of type Terminal.

TypeDef

Description

A definition of a parameter or return type in a Module.

Fields
Field Name Description
asEnum - EnumTypeDef If kind is ENUM, the enum-specific type definition. If kind is not ENUM, this will be null.
asInput - InputTypeDef If kind is INPUT, the input-specific type definition. If kind is not INPUT, this will be null.
asInterface - InterfaceTypeDef If kind is INTERFACE, the interface-specific type definition. If kind is not INTERFACE, this will be null.
asList - ListTypeDef If kind is LIST, the list-specific type definition. If kind is not LIST, this will be null.
asObject - ObjectTypeDef If kind is OBJECT, the object-specific type definition. If kind is not OBJECT, this will be null.
asScalar - ScalarTypeDef If kind is SCALAR, the scalar-specific type definition. If kind is not SCALAR, this will be null.
id - TypeDefID! A unique identifier for this TypeDef.
kind - TypeDefKind! The kind of type this is (e.g. primitive, list, object).
optional - Boolean! Whether this type can be set to null. Defaults to false.
withConstructor - TypeDef! Adds a function for constructing a new instance of an Object TypeDef, failing if the type is not an object.
Arguments
function - FunctionID!
withEnum - TypeDef!

Returns a TypeDef of kind Enum with the provided name.

Note that an enum's values may be omitted if the intent is only to refer to an enum. This is how functions are able to return their own, or any other circular reference.

Arguments
description - String

A doc string for the enum, if any

name - String!

The name of the enum

withEnumValue - TypeDef! Adds a static value for an Enum TypeDef, failing if the type is not an enum.
Arguments
description - String

A doc string for the value, if any

value - String!

The name of the value in the enum

withField - TypeDef! Adds a static field for an Object TypeDef, failing if the type is not an object.
Arguments
description - String

A doc string for the field, if any

name - String!

The name of the field in the object

typeDef - TypeDefID!

The type of the field

withFunction - TypeDef! Adds a function for an Object or Interface TypeDef, failing if the type is not one of those kinds.
Arguments
function - FunctionID!
withInterface - TypeDef! Returns a TypeDef of kind Interface with the provided name.
Arguments
description - String
name - String!
withKind - TypeDef! Sets the kind of the type.
Arguments
kind - TypeDefKind!
withListOf - TypeDef! Returns a TypeDef of kind List with the provided type for its elements.
Arguments
elementType - TypeDefID!
withObject - TypeDef!

Returns a TypeDef of kind Object with the provided name.

Note that an object's fields and functions may be omitted if the intent is only to refer to an object. This is how functions are able to return their own object, or any other circular reference.

Arguments
description - String
name - String!
withOptional - TypeDef! Sets whether this type can be set to null.
Arguments
optional - Boolean!
withScalar - TypeDef! Returns a TypeDef of kind Scalar with the provided name.
Arguments
description - String
name - String!

TypeDefID

Description

The TypeDefID scalar type represents an identifier for an object of type TypeDef.

TypeDefKind

Description

Distinguishes the different kinds of TypeDefs.

Values
Enum Value Description

STRING_KIND

A string value.

INTEGER_KIND

An integer value.

BOOLEAN_KIND

A boolean value.

SCALAR_KIND

A scalar value of any basic kind.

LIST_KIND

A list of values all having the same type.

Always paired with a ListTypeDef.

OBJECT_KIND

A named type defined in the GraphQL schema, with fields and functions.

Always paired with an ObjectTypeDef.

INTERFACE_KIND

A named type of functions that can be matched+implemented by other objects+interfaces.

Always paired with an InterfaceTypeDef.

INPUT_KIND

A graphql input type, used only when representing the core API via TypeDefs.

VOID_KIND

A special kind used to signify that no value is returned.

This is used for functions that have no return value. The outer TypeDef specifying this Kind is always Optional, as the Void is never actually represented.

ENUM_KIND

A GraphQL enum type and its values

Always paired with an EnumTypeDef.

Example
"STRING_KIND"

Void

Description

The absence of a value.

A Null Void is used as a placeholder for resolvers that do not return anything.