Dagger GraphQL API Reference
Queries
cacheVolume
Description
Constructs a cache volume for a given cache key.
Type
Arguments
Name | Description |
---|---|
key - String!
|
A string identifier to target this cache volume (e.g. "myapp-cache"). |
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
Arguments
Name | Description |
---|---|
id - ContainerID
|
|
platform - Platform
|
Example
query {
container {
from(address: "alpine") {
defaultArgs
entrypoint
platform
rootfs {
entries
}
}
}
}
defaultPlatform
Description
The default platform of the builder.
Type
directory
Description
Load a directory by ID. No argument produces an empty directory.
Type
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
}
}
}
}
}
}
file
Description
Loads a file by ID.
Example
query {
file(id: "eyJsbGIiOnsiZGVmIjpbIklqWVNOQWovLy8vLy8vLy8vLzhCRVAvLy8vLy8vLy8vL3dFcUhBb0VMMlp2YnhDa0F4b0dTR1ZzYkc4aEtQLy8vLy8vLy8vLy93RlNBRm9BIiwiQ2trS1IzTm9ZVEkxTmpwak1EQTVPV1U1TURrNFpEVmlObUkyWVdWaFpXWXpObVpsTnpsaU9UUTVOVEF4TnpoalptRmpPRGxsWVdKbE5XRmtZbUprTkdZeFptWXdNV0l3TkdWbSJdLCJtZXRhZGF0YSI6eyJzaGEyNTY6NWNjOGQ1M2VkZTRjYzUyODQ0OTIyYWFhZDlhYjIzMzc3MzY3NWMwMDJjOTM5NGZhYTk0OTg1OTZmNGFjMWRiNiI6eyJjYXBzIjp7ImNvbnN0cmFpbnRzIjp0cnVlLCJwbGF0Zm9ybSI6dHJ1ZX19LCJzaGEyNTY6YzAwOTllOTA5OGQ1YjZiNmFlYWVmMzZmZTc5Yjk0OTUwMTc4Y2ZhYzg5ZWFiZTVhZGJiZDRmMWZmMDFiMDRlZiI6eyJjYXBzIjp7ImZpbGUuYmFzZSI6dHJ1ZX19fSwiU291cmNlIjp7ImxvY2F0aW9ucyI6eyJzaGEyNTY6YzAwOTllOTA5OGQ1YjZiNmFlYWVmMzZmZTc5Yjk0OTUwMTc4Y2ZhYzg5ZWFiZTVhZGJiZDRmMWZmMDFiMDRlZiI6e319fX0sImZpbGUiOiJmb28iLCJwbGF0Zm9ybSI6eyJhcmNoaXRlY3R1cmUiOiIiLCJvcyI6IiJ9fQ==") {
contents
export(path: "greeting")
}
}
git
Description
Queries a git repository.
Type
Example
query {
git(url: "https://github.com/dagger/dagger", keepGitDir: true) {
branch(name: "main") {
tree {
file(path: ".git/refs/heads/main") {
contents
}
}
}
}
}
host
Description
Queries the host environment.
Type
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: ".")
}
}
}
}
http
Description
Returns a file containing an http remote url content.
pipeline
Description
Creates a named sub-pipeline
Example
secret
Description
Loads a secret from its ID.
Example
query {
secret(id: "eyJob3N0X2VudiI6IkhPTUUifQ==") {
plaintext
}
}
socket
Description
Loads a socket by its ID.
Example
query {
socket(id: "eyJob3N0X3BhdGgiOiIvdmFyL3J1bi9kb2NrZXIuc29jayJ9") {
id
}
}
Types
Boolean
Description
The Boolean
scalar type represents true
or false
.
BuildArg
CacheID
Description
A global cache volume identifier.
CacheVolume
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 |
from - Container! |
Initializes this container from the base image published at the given address. |
Arguments
|
|
build - Container! |
Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs. |
Arguments
|
|
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
|
|
withFS - Container! |
Initializes this container from this DirectoryID. Replaced by withRootfs .
|
Arguments
|
|
directory - Directory! |
Retrieves a directory at the given path. Mounts are included. |
Arguments
|
|
file - File! |
Retrieves a file at the given path. Mounts are included. |
Arguments
|
|
user - String |
Retrieves the user to be set for all commands. |
withUser - Container! |
Retrieves this containers with a different command user. |
Arguments
|
|
workdir - String |
Retrieves the working directory for all commands. |
withWorkdir - Container! |
Retrieves this container with a different working directory. |
Arguments
|
|
envVariables - [EnvVariable!]! |
Retrieves the list of environment variables passed to commands. |
envVariable - String |
Retrieves the value of the specified environment variable. |
Arguments
|
|
withEnvVariable - Container! |
Retrieves this container plus the given environment variable. |
labels - [Label!]! |
Retrieves the list of labels passed to container. |
label - String |
Retrieves the value of the specified label. |
Arguments
|
|
withLabel - Container! |
Retrieves this container plus the given label. |
withoutLabel - Container! |
Retrieves this container minus the given environment label. |
Arguments
|
|
withSecretVariable - Container! |
Retrieves this container plus an env variable containing the given secret. |
withoutEnvVariable - Container! |
Retrieves this container minus the given environment variable. |
Arguments
|
|
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
|
|
defaultArgs - [String!] |
Retrieves default arguments for future commands. |
withDefaultArgs - Container! |
Configures default arguments for future commands. |
Arguments
|
|
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
|
|
withMountedFile - Container! |
Retrieves this container plus a file mounted at the given path. |
withMountedTemp - Container! |
Retrieves this container plus a temporary directory mounted at the given path. |
Arguments
|
|
withMountedCache - Container! |
Retrieves this container plus a cache volume mounted at the given path. |
Arguments |
|
withMountedSecret - Container! |
Retrieves this container plus a secret mounted into a file at the given path. |
withoutMount - Container! |
Retrieves this container after unmounting everything at the given path. |
Arguments
|
|
withFile - Container! |
Retrieves this container plus the contents of the given file copied to the given path. |
withNewFile - Container! |
Retrieves this container plus a new file written at the given path. |
withDirectory - Container! |
Retrieves this container plus a directory written at the given path. |
Arguments |
|
withUnixSocket - Container! |
Retrieves this container plus a socket forwarded to the given Unix socket path. |
withoutUnixSocket - Container! |
Retrieves this container with a previously added Unix socket removed. |
Arguments
|
|
withExec - Container! |
Retrieves this container after executing the specified command inside it. |
Arguments
|
|
exec - Container! |
Retrieves this container after executing the specified command inside it. Replaced by withExec .
|
Arguments
|
|
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
|
|
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
|
ContainerID
Description
A unique container identifier. Null designates an empty container (scratch).
Directory
Description
A directory.
Fields
Field Name | Description |
---|---|
id - DirectoryID! |
The content-addressed identifier of the directory. |
pipeline - Directory! |
Creates a named sub-pipeline. |
entries - [String!]! |
Returns a list of files and directories at the given path. |
Arguments
|
|
file - File! |
Retrieves a file at the given path. |
Arguments
|
|
withFile - Directory! |
Retrieves this directory plus the contents of the given file copied to the given path. |
withNewFile - Directory! |
Retrieves this directory plus a new file written at the given path. |
withoutFile - Directory! |
Retrieves this directory with the file at the given path removed. |
Arguments
|
|
directory - Directory! |
Retrieves a directory at the given path. |
Arguments
|
|
withDirectory - Directory! |
Retrieves this directory plus a directory written at the given path. |
Arguments
|
|
withNewDirectory - Directory! |
Retrieves this directory plus a new directory created at the given path. |
withoutDirectory - Directory! |
Retrieves this directory with the directory at the given path removed. |
Arguments
|
|
diff - Directory! |
Gets the difference between this directory and an another directory. |
Arguments
|
|
export - Boolean! |
Writes the contents of the directory to a path on the host. |
Arguments
|
|
dockerBuild - Container! |
Builds a new Docker container from this directory. |
Arguments
|
|
withTimestamps - Directory! |
Retrieves this directory with all file/dir timestamps set to the given time, in seconds from the Unix epoch. |
Arguments
|
DirectoryID
Description
A content-addressed directory identifier.
EnvVariable
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
|
|
withTimestamps - File! |
Retrieves this file with its created/modified timestamps set to the given time, in seconds from the Unix epoch. |
Arguments
|
FileID
Description
A file identifier.
GitRef
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
|
|
tags - [String!]! |
Lists of tags on the repository. |
tag - GitRef! |
Returns details on one tag. |
Arguments
|
|
commit - GitRef! |
Returns details on one commit. |
Arguments
|
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.
|
directory - Directory! |
Accesses a directory on the host. |
envVariable - HostVariable |
Accesses an environment variable on the host. |
Arguments
|
|
unixSocket - Socket! |
Accesses a Unix socket on the host. |
Arguments
|
HostVariable
Int
Description
The Int
scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Label
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).
Secret
SecretID
Description
A unique identifier for a secret.
Socket
SocketID
Description
A content-addressed socket identifier.
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.