Query
API reference
The root of the DAG.
Implements Node
defaultPlatform- The default platform of the engine.
id- A unique identifier for this Query.
version- Get the current Dagger Engine version.
address- initialize an address to load directories, containers, secrets or other object types.
cacheVolume- Constructs a cache volume for a given cache key.
changeset- Creates an empty changeset
cloud- Dagger Cloud configuration and state
container- Creates a scratch container, with no image or metadata.
currentEnv- Returns the current environment
currentFunctionCall- The FunctionCall context that the SDK caller is currently executing in.
currentModule- The module currently being served in the session, if any.
currentTypeDefs- The TypeDef representations of the objects currently being served in the session.
currentWorkspace- Detect and return the current workspace.
directory- Creates an empty directory.
engine- The Dagger engine container configuration and state
env- Initializes a new environment
envFile- Initialize an environment file
error- Create a new error.
file- Creates a file with the specified contents.
function- Creates a function.
generatedCode- Create a code generation result, given a directory containing the generated code.
git- Queries a Git repository.
host- Queries the host environment.
http- Returns a file containing an http remote url content.
json- Initialize a JSON value
llm- Initialize a Large Language Model (LLM)
module- Create a new module.
moduleSource- Create a new module source instance from a source ref string
node- Load any object by its ID.
secret- Creates a new secret.
setSecret- Sets a secret given a user defined name to its plaintext and returns the secret.
sourceMap- Creates source map metadata.
typeDef- Create a new TypeDef.
defaultPlatform: Platform!
The default platform of the engine.
id: ID!
A unique identifier for this Query.
version: String!
Get the current Dagger Engine version.
address(value: String!): Address!
initialize an address to load directories, containers, secrets or other object types.
value: String!
cacheVolume(key: String!,source: Directory,sharing: CacheSharingMode = SHARED,owner: String = ""): CacheVolume!
Constructs a cache volume for a given cache key.
key: String!A string identifier to target this cache volume (e.g., "modules-cache").
source: DirectoryIdentifier of the directory to use as the cache volume's root.
sharing: CacheSharingMode = SHAREDSharing mode of the cache volume.
owner: String = ""A user:group to set for the cache volume root.
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.
container(platform: Platform): Container!
Creates a scratch container, with no image or metadata.
To pull an image, follow up with the "from" function.
platform: PlatformPlatform to initialize the container with. Defaults to the native platform of the current engine
currentEnv: Env!Experimental
Returns the current environment
When called from a function invoked via an LLM tool call, this will be the LLM's current environment, including any modifications made through calling tools. Env values returned by functions become the new environment for subsequent calls, and Changeset values returned by functions are applied to the environment's workspace.
When called from a module function outside of an LLM, this returns an Env with the current module installed, and with the current module's source directory as its workspace.
Experimental: Programmatic env access is speculative and might be replaced.
currentFunctionCall: FunctionCall!
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.
currentModule: CurrentModule!
The module currently being served in the session, if any.
currentTypeDefs(returnAllTypes: Boolean = false, hideCore: Boolean): [TypeDef!]!
The TypeDef representations of the objects currently being served in the session.
returnAllTypes: Boolean = falseReturn the full referenced typedef closure instead of only top-level served typedefs.
hideCore: BooleanStrip core API functions from the Query type, leaving only module-sourced functions (constructors, entrypoint proxies, etc.).
Core types (Container, Directory, etc.) are kept so return types and method chaining still work.
currentWorkspace: Workspace!Experimental
Detect and return the current workspace.
Experimental: Highly experimental API extracted from a more ambitious workspace implementation.
env(privileged: Boolean = false, writable: Boolean = false): Env!Experimental
Initializes a new environment
Experimental: Environments are not yet stabilized
privileged: Boolean = falseGive the environment the same privileges as the caller: core API including host access, current module, and dependencies
writable: Boolean = falseAllow new outputs to be declared and saved in the environment
envFile(expand: Boolean): EnvFile!
Initialize an environment file
expand: BooleanReplace "${VAR}" or "$VAR" with the value of other vars
file(name: String!,contents: String!,permissions: Int = 420): File!
Creates a file with the specified contents.
name: String!Name of the new file. Example: "foo.txt"
contents: String!Contents of the new file. Example: "Hello world!"
permissions: Int = 420Permissions of the new file. Example: 0600
function(name: String!, returnType: TypeDef!): Function!
Creates a function.
name: String!Name of the function, in its original format from the implementation language.
returnType: TypeDef!Return type of the function.
generatedCode(code: Directory!): GeneratedCode!
Create a code generation result, given a directory containing the generated code.
code: Directory!
git(url: String!,keepGitDir: Boolean = true,sshKnownHosts: String = "",sshAuthSocket: Socket,httpAuthUsername: String = "",httpAuthToken: Secret,httpAuthHeader: Secret,experimentalServiceHost: Service): GitRepository!
Queries a Git repository.
url: String!URL of the git repository.
Can be formatted as
https://{host}/{owner}/{repo},git@{host}:{owner}/{repo}.Suffix ".git" is optional.
keepGitDir: Boolean = trueDEPRECATED: Set to true to keep .git directory.
sshKnownHosts: String = ""Set SSH known hosts
sshAuthSocket: SocketSet SSH auth socket
httpAuthUsername: String = ""Username used to populate the password during basic HTTP Authorization
httpAuthToken: SecretSecret used to populate the password during basic HTTP Authorization
httpAuthHeader: SecretSecret used to populate the Authorization HTTP header
experimentalServiceHost: ServiceA service which must be started before the repo is fetched.
http(url: String!,name: String,permissions: Int,checksum: String,authHeader: Secret,experimentalServiceHost: Service): File!
Returns a file containing an http remote url content.
url: String!HTTP url to get the content from (e.g., "https://docs.dagger.io").
name: StringFile name to use for the file. Defaults to the last part of the URL.
permissions: IntPermissions to set on the file.
checksum: StringExpected digest of the downloaded content (e.g., "sha256:...").
authHeader: SecretSecret used to populate the Authorization HTTP header
experimentalServiceHost: ServiceA service which must be started before the URL is fetched.
llm(model: String, maxAPICalls: Int): LLM!Experimental
Initialize a Large Language Model (LLM)
Experimental: LLM support is not yet stabilized
model: StringModel to use
maxAPICalls: IntCap the number of API calls for this LLM
moduleSource(refString: String!,refPin: String = "",disableFindUp: Boolean = false,allowNotExists: Boolean = false,requireKind: ModuleSourceKind): ModuleSource!
Create a new module source instance from a source ref string
refString: String!The string ref representation of the module source
refPin: String = ""The pinned version of the module source
disableFindUp: Boolean = falseIf true, do not attempt to find a module config file in a parent directory of the provided path. Only relevant for local module sources.
allowNotExists: Boolean = falseIf true, do not error out if the provided ref string is a local path and does not exist yet. Useful when initializing new modules in directories that don't exist yet.
requireKind: ModuleSourceKindIf set, error out if the ref string is not of the provided requireKind.
secret(uri: String!, cacheKey: String): Secret!
Creates a new secret.
uri: String!The URI of the secret store
cacheKey: StringIf set, the given string will be used as the cache key for this secret. This means that any secrets with the same cache key will be considered equivalent in terms of cache lookups, even if they have different URIs or plaintext values.
For example, two secrets with the same cache key provided as secret env vars to other wise equivalent containers will result in the container withExecs hitting the cache for each other.
If not set, the cache key for the secret will be derived from its plaintext value as looked up when the secret is constructed.
setSecret(name: String!, plaintext: String!): Secret!
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.
name: String!The user defined name for this secret
plaintext: String!The plaintext of the secret