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 root, 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.

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.

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.

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.

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.

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 root, 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.

changes: Changeset!

Return this workspace's pending overlay changes.

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: Boolean

When true, only return annotated check functions; exclude generate-as-checks

onlyGenerate: Boolean

When 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 = false

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

name: String!

Module name to inspect.

modules: [WorkspaceModule!]!

List modules defined in the workspace configuration.

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.

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 = false

Interpret the pattern as a literal string instead of a regular expression.

multiline: Boolean = false

Enable searching across multiple lines.

dotall: Boolean = false

Allow the . pattern to match newlines in multiline mode.

insensitive: Boolean = false

Enable case-insensitive matching.

skipIgnored: Boolean = false

Honor .gitignore, .ignore, and .rgignore files.

skipHidden: Boolean = false

Skip hidden files (files starting with .).

filesOnly: Boolean = false

Only return matching files, not lines and content

limit: Int

Limit 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 = false

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

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 = false

Write to the workspace config directory at the workspace cwd.

withInitClient(path: String!,sdk: String!,module: String!,args: JSON,here: Boolean = false): Workspace!

Return this workspace with a generated API client initialized.

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: JSON

SDK-specific init arguments.

here: Boolean = false

Write to the workspace config directory at the workspace cwd.

withInitModule(name: String!,sdk: String!,path: String = "",source: String = "",include: [String!] = [],args: JSON,here: Boolean = false): Workspace!

Return this workspace with a new module initialized.

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: JSON

SDK-specific init arguments.

here: Boolean = false

Write to the workspace config directory at the workspace cwd.

withModule(ref: String!,name: String = "",here: Boolean = false): Workspace!

Return this workspace with a module installed in its config.

ref: String!

Module reference to install.

name: String = ""

Override name for the installed module entry.

here: Boolean = false

Write to the workspace config directory at the workspace cwd.

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 = 420

Permissions 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 = false

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

key: String!

Dotted key path (e.g. modules.greeter.settings.greeting).

here: Boolean = false

Write to the workspace config directory at the workspace cwd.

withoutModule(name: String!, here: Boolean = false): Workspace!

Return this workspace with a module removed from its config.

name: String!

Name of the installed module entry to remove.

here: Boolean = false

Write 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 = false

Write 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 = false

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

References

Returned by

Binding.asWorkspaceDirectory.asWorkspaceGitRef.asWorkspaceGitRepository.asWorkspaceQuery.currentWorkspace

Accepted as an argument by

Env.withWorkspaceInput (value)