Workspace
API reference
A Dagger workspace detected from the current working directory or constructed from a Directory.
Implements Node
address- Canonical Dagger address of the workspace location, or an opaque identity for synthetic workspaces.
configFile- Selected native workspace config file relative to the workspace cwd, if any.
configRead- Read a configuration value from dagger.toml.
cwd- Current location within the workspace root.
envList- List named environments defined in the workspace configuration.
export- Write this workspace's pending changes to its local Git workspace.
findUp- Search for a file or directory by walking up from the start path within the workspace.
glob- Returns a list of files and directories that match the given pattern.
id- A unique identifier for this Workspace.
agents- Return all agent middlewares from modules loaded in the workspace.
changes- Return this workspace's pending overlay changes.
checks- Return all checks from modules loaded in the workspace.
directory- Returns a Directory from the workspace.
file- Returns a File from the workspace.
generators- Return all generators from modules loaded in the workspace.
git- Git state for this workspace. Errors if the workspace is not in a git repository.
migrate- Plan the explicit migration needed for the current workspace.
module- Return a module defined in the workspace configuration.
modules- List modules defined in the workspace configuration.
moduleSource- Load a module source from a path within the workspace.
reloaded- Return this workspace with its cached host reads invalidated, so subsequent file and directory reads re-read the live host instead of a snapshot cached earlier in the session.
sdk- An installed SDK, by name.
sdks- Installed SDKs.
search- Searches for content matching the given regular expression or literal string.
services- Return all services from modules loaded in the workspace.
withChanges- Return this workspace with a changeset applied, without mutating the source.
withConfigEnv- Return this workspace with a named config environment created.
withConfigValue- Return this workspace with a configuration value written.
withInitClient- Return this workspace with a generated API client initialized.
withInitModule- Return this workspace with a new module initialized.
withModule- Return this workspace with a module installed in its config.
withMountedDirectory- Return this workspace with a directory mounted read-only at the given path, without mutating the source.
withMountedFile- Return this workspace with a file mounted read-only at the given path, without mutating the source.
withNewDirectory- Return this workspace with a directory added, without mutating the source.
withNewFile- Return this workspace with a new or replaced file, without mutating the source.
withoutConfigEnv- Return this workspace with a named config environment removed.
withoutConfigValue- Return this workspace with a configuration value removed.
withoutDirectory- Return this workspace with a directory removed, without mutating the source.
withoutFile- Return this workspace with a file removed, without mutating the source.
withoutModule- Return this workspace with a module removed from its config.
withoutSDK- Return this workspace with an SDK removed from its config.
withSDK- Return this workspace with an SDK installed in its config.
withUpdatedLock- Return this workspace with refreshed lockfile state.
withWorkdir- Return this workspace with its working directory pointed at the given workspace-relative path.
address: String!
Canonical Dagger address of the workspace location, or an opaque identity for synthetic workspaces.
configFile: String!
Selected native workspace config file relative to the workspace cwd, if any.
configRead(key: String = ""): String!
Read a configuration value from dagger.toml.
If key is empty, returns the full config.
If key points to a scalar, returns the value.
If key points to a table, returns flattened dotted-key output.
key: String = ""Dotted key path (e.g. modules.greeter.source). Empty for full config.
cwd: String!
Current location within the workspace root.
The workspace root is returned as "/".
Relative paths in workspace APIs resolve from here.
envList: [String!]!
List named environments defined in the workspace configuration.
export: Void!
Write this workspace's pending changes to its local Git workspace.
findUp(name: String!, from: String = "."): String
Search for a file or directory by walking up from the start path within the workspace.
Returns the absolute workspace path if found, or null if not found.
Relative start paths resolve from the workspace cwd.
The search stops at the workspace root and will not traverse above it.
name: String!The name of the file or directory to search for.
from: String = "."Path to start the search from. Relative paths resolve from the workspace cwd; absolute paths resolve from the workspace root.
glob(pattern: String!): [String!]!
Returns a list of files and directories that match the given pattern.
Patterns match paths relative to the workspace root.
pattern: String!Pattern to match (e.g., "*.md").
id: ID!
A unique identifier for this Workspace.
agents(include: [String!]): AgentGroup!
Return all agent middlewares from modules loaded in the workspace.
include: [String!]Only include agents matching the specified patterns
checks(include: [String!],skip: [String!],noGenerate: Boolean,onlyGenerate: Boolean): CheckGroup!
Return all checks from modules loaded in the workspace.
include: [String!]Only include checks matching the specified patterns
skip: [String!]Skip checks matching the specified patterns
noGenerate: BooleanWhen true, only return annotated check functions; exclude generate-as-checks
onlyGenerate: BooleanWhen true, only return generate-as-checks; exclude annotated check functions
directory(path: String!,exclude: [String!] = [],include: [String!] = [],gitignore: Boolean = false): Directory!
Returns a Directory from the workspace.
Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.
path: String!Location of the directory to retrieve. Relative paths (e.g., "src") resolve from the workspace cwd; absolute paths (e.g., "/src") resolve from the workspace root.
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.*"]).
gitignore: Boolean = falseApply .gitignore filter rules inside the directory.
file(path: String!): File!
Returns a File from the workspace.
Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.
path: String!Location of the file to retrieve. Relative paths (e.g., "go.mod") resolve from the workspace cwd; absolute paths (e.g., "/go.mod") resolve from the workspace root.
generators(include: [String!]): GeneratorGroup!
Return all generators from modules loaded in the workspace.
include: [String!]Only include generators matching the specified patterns
git: WorkspaceGit!
Git state for this workspace. Errors if the workspace is not in a git repository.
migrate: WorkspaceMigration!
Plan the explicit migration needed for the current workspace.
The returned plan has an empty changeset and no steps when no migration is needed.
module(name: String!): WorkspaceModule!
Return a module defined in the workspace configuration.
Reflects the selected env's effective view.
name: String!Module name to inspect.
modules: [WorkspaceModule!]!
List modules defined in the workspace configuration.
Reflects the selected env's effective view.
moduleSource(path: String!): ModuleSource!
Load a module source from a path within the workspace.
Relative paths (e.g., "foo") resolve from the workspace cwd; absolute paths (e.g., "/foo") resolve from the workspace root.
Fails if the path does not point to an initialized module.
path: String!Location of the module source to load, relative to the workspace cwd or absolute from the workspace root.
reloaded: Workspace!
Return this workspace with its cached host reads invalidated, so subsequent file and directory reads re-read the live host instead of a snapshot cached earlier in the session.
sdk(name: String!): WorkspaceSDK!
An installed SDK, by name.
name: String!SDK name to look up.
sdks: [WorkspaceSDK!]!
Installed SDKs.
search(paths: [String!] = [],globs: [String!] = [],pattern: String!,literal: Boolean = false,multiline: Boolean = false,dotall: Boolean = false,insensitive: Boolean = false,skipIgnored: Boolean = false,skipHidden: Boolean = false,filesOnly: Boolean = false,limit: Int): [SearchResult!]!
Searches for content matching the given regular expression or literal string.
Uses Rust regex syntax; escape literal ., [, ], {, }, | with backslashes.
Runs ripgrep on the client host, falling back to grep if unavailable.
paths: [String!] = []Directory or file paths to search
globs: [String!] = []Glob patterns to match (e.g., "*.md")
pattern: String!The text to match.
literal: Boolean = falseInterpret the pattern as a literal string instead of a regular expression.
multiline: Boolean = falseEnable searching across multiple lines.
dotall: Boolean = falseAllow the . pattern to match newlines in multiline mode.
insensitive: Boolean = falseEnable case-insensitive matching.
skipIgnored: Boolean = falseHonor .gitignore, .ignore, and .rgignore files.
skipHidden: Boolean = falseSkip hidden files (files starting with .).
filesOnly: Boolean = falseOnly return matching files, not lines and content
limit: IntLimit the number of results to return
services(include: [String!]): UpGroup!
Return all services from modules loaded in the workspace.
include: [String!]Only include services matching the specified patterns
withChanges(changes: Changeset!): Workspace!
Return this workspace with a changeset applied, without mutating the source.
changes: Changeset!Changes to apply.
withConfigEnv(name: String!, here: Boolean = false): Workspace!
Return this workspace with a named config environment created.
name: String!Environment name.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withConfigValue(key: String!,value: String!,values: [String!],here: Boolean = false): Workspace!
Return this workspace with a configuration value written.
When the session selects an env, the key is scoped to that env's overlay and the env is created if missing.
key: String!Dotted key path.
value: String!Value to set. Bools, integers, and comma-separated arrays are auto-detected.
values: [String!]List value to set. Elements are stored verbatim, with no auto-detection. Mutually exclusive with value.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withInitClient(path: String!,sdk: String!,module: String!,args: JSON,here: Boolean = false,noGenerate: Boolean = false): Workspace!
Return this workspace with a generated API client initialized.
The SDK's generators run for the new client, so the returned workspace carries its generated bindings.
path: String!Workspace-relative output directory for the generated client.
sdk: String!Workspace SDK name or module entry name to use.
module: String!Workspace-relative path or canonical ref for the module the client binds to.
args: JSONSDK-specific init arguments.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
noGenerate: Boolean = falseSkip running the SDK's generators for the new client.
withInitModule(name: String!,sdk: String!,path: String = "",source: String = "",include: [String!] = [],args: JSON,here: Boolean = false,noGenerate: Boolean = false): Workspace!
Return this workspace with a new module initialized.
The SDK's generators run for the new module, so the returned workspace carries the generated code it needs to be loadable.
name: String!Name of the new module.
sdk: String!Workspace SDK name or module entry name to use.
path: String = ""Workspace-relative path for the new module.
source: String = ""Source subpath within the new module.
include: [String!] = []Additional include patterns for the module.
args: JSONSDK-specific init arguments.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
noGenerate: Boolean = falseSkip running the SDK's generators for the new module.
withModule(ref: String!,name: String = "",here: Boolean = false): Workspace!
Return this workspace with a module installed in its config.
When the session selects an env, the module is recorded in that env's overlay and the env is created if missing.
ref: String!Module reference to install.
name: String = ""Override name for the installed module entry.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withMountedDirectory(path: String!, source: Directory!): Workspace!
Return this workspace with a directory mounted read-only at the given path, without mutating the source.
Mounted content is readable through the normal workspace file tools but shadows the source at the mount path and stays out of the pending changeset: it never appears in changes, is never exported, and cannot be modified.
path: String!Location of the mounted directory. Relative paths resolve from the workspace cwd.
source: Directory!Directory to mount.
withMountedFile(path: String!, source: File!): Workspace!
Return this workspace with a file mounted read-only at the given path, without mutating the source.
Mounted content is readable through the normal workspace file tools but shadows the source at the mount path and stays out of the pending changeset: it never appears in changes, is never exported, and cannot be modified.
path: String!Location of the mounted file. Relative paths resolve from the workspace cwd.
source: File!File to mount.
withNewDirectory(path: String!, source: Directory!): Workspace!
Return this workspace with a directory added, without mutating the source.
path: String!Path of the added directory. Relative paths resolve from the workspace cwd.
source: Directory!Directory to add.
withNewFile(path: String!,contents: String!,permissions: Int = 420): Workspace!
Return this workspace with a new or replaced file, without mutating the source.
path: String!Path of the new file. Relative paths resolve from the workspace cwd.
contents: String!Contents of the new file.
permissions: Int = 420Permissions of the new file.
withoutConfigEnv(name: String!, here: Boolean = false): Workspace!
Return this workspace with a named config environment removed.
name: String!Environment name.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withoutConfigValue(key: String!, here: Boolean = false): Workspace!
Return this workspace with a configuration value removed.
Errors when the key is not currently set.
When the session selects an env, the key is scoped to that env's overlay.
key: String!Dotted key path (e.g. modules.greeter.settings.greeting).
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withoutDirectory(path: String!): Workspace!
Return this workspace with a directory removed, without mutating the source.
path: String!Path of the directory to remove. Relative paths resolve from the workspace cwd.
withoutFile(path: String!): Workspace!
Return this workspace with a file removed, without mutating the source.
path: String!Path of the file to remove. Relative paths resolve from the workspace cwd.
withoutModule(name: String!, here: Boolean = false): Workspace!
Return this workspace with a module removed from its config.
When the session selects an env, only that env's overlay entry is removed.
name: String!Name of the installed module entry to remove.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withoutSDK(name: String!, here: Boolean = false): Workspace!
Return this workspace with an SDK removed from its config.
name: String!Name of the installed SDK entry to remove.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
withSDK(ref: String!,name: String = "",here: Boolean = false,asSdkName: String = ""): Workspace!
Return this workspace with an SDK installed in its config.
ref: String!SDK module reference to install.
name: String = ""Override name for the installed SDK entry.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
asSdkName: String = ""User-facing SDK name to persist under
[modules.<name>.as-sdk] name = ....
withUpdatedLock: Workspace!
Return this workspace with refreshed lockfile state.
withWorkdir(path: String!): Workspace!
Return this workspace with its working directory pointed at the given workspace-relative path.
path: String!Workspace-relative path to use as the working directory.