Dagger GraphQL API Reference

Queries

cacheVolume

Description

Constructs a cache volume for a given cache key.

Type

CacheVolume!

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

Try it in the API Playground!

Queries

container

Description

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.

Type

Container!

Arguments
Name Description
id - ContainerID
platform - Platform
Example
query {
  container {
    from(address: "alpine") {
      defaultArgs
      entrypoint
      platform
      rootfs {
        entries
      }
    }
  }
}

Try it in the API Playground!

Queries

defaultPlatform

Description

The default platform of the builder.

Type

Platform!

Example
query {
  defaultPlatform
}

Try it in the API Playground!

Queries

directory

Description

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

Type

Directory!

Arguments
Name Description
id - DirectoryID
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!

Queries

file

Description

Loads a file by ID.

Type

File

Arguments
Name Description
id - FileID!
Example
query {
  file(id: "eyJsbGIiOnsiZGVmIjpbIklqWVNOQWovLy8vLy8vLy8vLzhCRVAvLy8vLy8vLy8vL3dFcUhBb0VMMlp2YnhDa0F4b0dTR1ZzYkc4aEtQLy8vLy8vLy8vLy93RlNBRm9BIiwiQ2trS1IzTm9ZVEkxTmpwak1EQTVPV1U1TURrNFpEVmlObUkyWVdWaFpXWXpObVpsTnpsaU9UUTVOVEF4TnpoalptRmpPRGxsWVdKbE5XRmtZbUprTkdZeFptWXdNV0l3TkdWbSJdLCJtZXRhZGF0YSI6eyJzaGEyNTY6NWNjOGQ1M2VkZTRjYzUyODQ0OTIyYWFhZDlhYjIzMzc3MzY3NWMwMDJjOTM5NGZhYTk0OTg1OTZmNGFjMWRiNiI6eyJjYXBzIjp7ImNvbnN0cmFpbnRzIjp0cnVlLCJwbGF0Zm9ybSI6dHJ1ZX19LCJzaGEyNTY6YzAwOTllOTA5OGQ1YjZiNmFlYWVmMzZmZTc5Yjk0OTUwMTc4Y2ZhYzg5ZWFiZTVhZGJiZDRmMWZmMDFiMDRlZiI6eyJjYXBzIjp7ImZpbGUuYmFzZSI6dHJ1ZX19fSwiU291cmNlIjp7ImxvY2F0aW9ucyI6eyJzaGEyNTY6YzAwOTllOTA5OGQ1YjZiNmFlYWVmMzZmZTc5Yjk0OTUwMTc4Y2ZhYzg5ZWFiZTVhZGJiZDRmMWZmMDFiMDRlZiI6e319fX0sImZpbGUiOiJmb28iLCJwbGF0Zm9ybSI6eyJhcmNoaXRlY3R1cmUiOiIiLCJvcyI6IiJ9fQ==") {
      contents
    export(path: "greeting")
  }
}

Try it in the API Playground!

Queries

git

Description

Queries a git repository.

Type

GitRepository!

Arguments
Name Description
url - String!
keepGitDir - Boolean
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!

Queries

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!

Queries

http

Description

Returns a file containing an http remote url content.

Type

File!

Arguments
Name Description
url - String!
Example
query {
  http(url: "http://dagger.io") {
    size
    contents
  }
}

Try it in the API Playground!

Queries

pipeline

Description

Creates a named sub-pipeline

Type

Query!

Arguments
Name Description
name - String!
description - String
Example
Queries

secret

Description

Loads a secret from its ID.

Type

Secret!

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

Try it in the API Playground!

Queries

socket

Description

Loads a socket by its ID.

Type

Socket!

Arguments
Name Description
id - SocketID
Example
query {
  socket(id: "eyJob3N0X3BhdGgiOiIvdmFyL3J1bi9kb2NrZXIuc29jayJ9") {
    id
  }
}

Try it in the API Playground!

Types

Boolean

Description

The Boolean scalar type represents true or false.

Types

BuildArg

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

CacheID

Description

A global cache volume identifier.

Types

CacheVolume

Description

A directory whose contents persist across runs.

Fields
Field Name Description
id - CacheID!
Types

Container

Description

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

Fields
Field Name Description
id - ContainerID! A unique identifier for this container.
platform - Platform! The platform this container executes and publishes as.
pipeline - Container! Creates a named sub-pipeline
Arguments
name - String!
description - String
from - Container! Initializes this container from the base image published at the given address.
Arguments
address - String!

Image's address from its registry. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
build - Container! Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs.
Arguments
context - DirectoryID!

Directory context used by the Dockerfile.

dockerfile - String

Path to the Dockerfile to use. Defaults to './Dockerfile'.

buildArgs - [BuildArg!]

Additional build arguments.

target - String

Target build stage to build.
rootfs - Directory! Retrieves this container's root filesystem. Mounts are not included.
fs - Directory! Retrieves this container's root filesystem. Mounts are not included. Replaced by rootfs.
withRootfs - Container! Initializes this container from this DirectoryID.
Arguments
id - DirectoryID!
withFS - Container! Initializes this container from this DirectoryID. Replaced by withRootfs.
Arguments
id - DirectoryID!
directory - Directory! Retrieves a directory at the given path. Mounts are included.
Arguments
path - String!
file - File! Retrieves a file at the given path. Mounts are included.
Arguments
path - String!
user - String Retrieves the user to be set for all commands.
withUser - Container! Retrieves this containers with a different command user.
Arguments
name - String!
workdir - String Retrieves the working directory for all commands.
withWorkdir - Container! Retrieves this container with a different working directory.
Arguments
path - String!
envVariables - [EnvVariable!]! Retrieves the list of environment variables passed to commands.
envVariable - String Retrieves the value of the specified environment variable.
Arguments
name - String!
withEnvVariable - Container! Retrieves this container plus the given environment variable.
Arguments
name - String!
value - String!
labels - [Label!]! Retrieves the list of labels passed to container.
label - String Retrieves the value of the specified label.
Arguments
name - String!
withLabel - Container! Retrieves this container plus the given label.
Arguments
name - String!
value - String!
withoutLabel - Container! Retrieves this container minus the given environment label.
Arguments
name - String!
withSecretVariable - Container! Retrieves this container plus an env variable containing the given secret.
Arguments
name - String!
secret - SecretID!
withoutEnvVariable - Container! Retrieves this container minus the given environment variable.
Arguments
name - String!
entrypoint - [String!] Retrieves entrypoint to be prepended to the arguments of all commands.
withEntrypoint - Container! Retrieves this container but with a different command entrypoint.
Arguments
args - [String!]!
defaultArgs - [String!] Retrieves default arguments for future commands.
withDefaultArgs - Container! Configures default arguments for future commands.
Arguments
args - [String!]
mounts - [String!]! Retrieves the list of paths where a directory is mounted.
withMountedDirectory - Container! Retrieves this container plus a directory mounted at the given path.
Arguments
path - String!
source - DirectoryID!
withMountedFile - Container! Retrieves this container plus a file mounted at the given path.
Arguments
path - String!
source - FileID!
withMountedTemp - Container! Retrieves this container plus a temporary directory mounted at the given path.
Arguments
path - String!
withMountedCache - Container! Retrieves this container plus a cache volume mounted at the given path.
Arguments
path - String!
cache - CacheID!
source - DirectoryID
withMountedSecret - Container! Retrieves this container plus a secret mounted into a file at the given path.
Arguments
path - String!
source - SecretID!
withoutMount - Container! Retrieves this container after unmounting everything at the given path.
Arguments
path - String!
withFile - Container! Retrieves this container plus the contents of the given file copied to the given path.
Arguments
path - String!
source - FileID!
permissions - Int
withNewFile - Container! Retrieves this container plus a new file written at the given path.
Arguments
path - String!
contents - String
permissions - Int
withDirectory - Container! Retrieves this container plus a directory written at the given path.
Arguments
path - String!
directory - DirectoryID!
exclude - [String!]
include - [String!]
withUnixSocket - Container! Retrieves this container plus a socket forwarded to the given Unix socket path.
Arguments
path - String!
source - SocketID!
withoutUnixSocket - Container! Retrieves this container with a previously added Unix socket removed.
Arguments
path - String!
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.

stdin - String

Content to write to the command's standard input before closing.

redirectStdout - String

Redirect the command's standard output to a file in the container.

redirectStderr - String

Redirect the command's standard error to a file in the container.

experimentalPrivilegedNesting - Boolean

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.
exec - Container! Retrieves this container after executing the specified command inside it. Replaced by withExec.
Arguments
args - [String!]

Command to run instead of the container's default command.

stdin - String

Content to write to the command's standard input before closing.

redirectStdout - String

Redirect the command's standard output to a file in the container.

redirectStderr - String

Redirect the command's standard error to a file in the container.

experimentalPrivilegedNesting - Boolean

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.
exitCode - Int Exit code of the last executed command. Zero means success. Null if no command has been executed.
stdout - String The output stream of the last executed command. Null if no command has been executed.
stderr - String The error stream of the last executed command. Null if no command has been executed.
publish - String! Publishes this container as a new image to the specified address, for the platformVariants, returning a fully qualified ref.
Arguments
address - String!

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

platformVariants - [ContainerID!]

Identifiers for other platform specific containers. Used for multi-platform image.
export - Boolean! Writes the container as an OCI tarball to the destination file path on the host for the specified platformVariants. Return true on success.
Arguments
path - String!

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

platformVariants - [ContainerID!]

Identifiers for other platform specific containers. Used for multi-platform image.
Types

ContainerID

Description

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

Types

Directory

Description

A directory.

Fields
Field Name Description
id - DirectoryID! The content-addressed identifier of the directory.
pipeline - Directory! Creates a named sub-pipeline.
Arguments
name - String!
description - String
entries - [String!]! Returns a list of files and directories at the given path.
Arguments
path - String
file - File! Retrieves a file at the given path.
Arguments
path - String!
withFile - Directory! Retrieves this directory plus the contents of the given file copied to the given path.
Arguments
path - String!
source - FileID!
permissions - Int
withNewFile - Directory! Retrieves this directory plus a new file written at the given path.
Arguments
path - String!
contents - String!
permissions - Int
withoutFile - Directory! Retrieves this directory with the file at the given path removed.
Arguments
path - String!
directory - Directory! Retrieves a directory at the given path.
Arguments
path - String!
withDirectory - Directory! Retrieves this directory plus a directory written at the given path.
Arguments
path - String!
directory - DirectoryID!
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.*"]).
withNewDirectory - Directory! Retrieves this directory plus a new directory created at the given path.
Arguments
path - String!
permissions - Int
withoutDirectory - Directory! Retrieves this directory with the directory at the given path removed.
Arguments
path - String!
diff - Directory! Gets the difference between this directory and an another directory.
Arguments
other - DirectoryID!
export - Boolean! Writes the contents of the directory to a path on the host.
Arguments
path - String!
dockerBuild - Container! Builds a new Docker container from this directory.
Arguments
dockerfile - String

Path to the Dockerfile to use. Defaults to './Dockerfile'.

platform - Platform

The platform to build.

buildArgs - [BuildArg!]

Additional build arguments.

target - String

Target build stage to build.
withTimestamps - Directory! Retrieves this directory with all file/dir timestamps set to the given time, in seconds from the Unix epoch.
Arguments
timestamp - Int!
Types

DirectoryID

Description

A content-addressed directory identifier.

Types

EnvVariable

Description

A simple key value object that represents an environment variable.

Fields
Field Name Description
name - String! The environment variable name.
value - String! The environment variable value.
Types

File

Description

A file.

Fields
Field Name Description
id - FileID! Retrieves the content-addressed identifier of the file.
contents - String! Retrieves the contents of the file.
secret - Secret! Retrieves a secret referencing the contents of this file.
size - Int! Gets the size of the file, in bytes.
export - Boolean! Writes the file to a file path on the host.
Arguments
path - String!
withTimestamps - File! Retrieves this file with its created/modified timestamps set to the given time, in seconds from the Unix epoch.
Arguments
timestamp - Int!
Types

FileID

Description

A file identifier.

Types

GitRef

Description

A git ref (tag, branch or commit).

Fields
Field Name Description
digest - String! The digest of the current value of this ref.
tree - Directory! The filesystem tree at this ref.
Arguments
sshKnownHosts - String
sshAuthSocket - SocketID
Types

GitRepository

Description

A git repository.

Fields
Field Name Description
branches - [String!]! Lists of branches on the repository.
branch - GitRef! Returns details on one branch.
Arguments
name - String!
tags - [String!]! Lists of tags on the repository.
tag - GitRef! Returns details on one tag.
Arguments
name - String!
commit - GitRef! Returns details on one commit.
Arguments
id - String!
Types

Host

Description

Information about the host execution environment.

Fields
Field Name Description
workdir - Directory! Retrieves the current working directory on the host. Use directory with path set to '.' instead.
Arguments
exclude - [String!]
include - [String!]
directory - Directory! Accesses a directory on the host.
Arguments
path - String!
exclude - [String!]
include - [String!]
envVariable - HostVariable Accesses an environment variable on the host.
Arguments
name - String!
unixSocket - Socket! Accesses a Unix socket on the host.
Arguments
path - String!
Types

HostVariable

Description

An environment variable on the host environment.

Fields
Field Name Description
value - String! The value of this variable.
secret - Secret! A secret referencing the value of this variable.
Types

Int

Description

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

Types

Label

Description

A simple key value object that represents a label.

Fields
Field Name Description
name - String! The label name.
value - String! The label value.
Types

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

Types

Secret

Description

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

Fields
Field Name Description
id - SecretID! The identifier for this secret.
plaintext - String! The value of this secret.
Types

SecretID

Description

A unique identifier for a secret.

Types

Socket

Fields
Field Name Description
id - SocketID! The content-addressed identifier of the socket.
Types

SocketID

Description

A content-addressed socket identifier.

Types

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.

Documentation by Anvil SpectaQL