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.
configWrite- Write a configuration value to dagger.toml.
cwd- Current location within the workspace root.
envCreate- Create a named workspace environment if it does not already exist.
envList- List named environments defined in the workspace configuration.
envRemove- Remove a named workspace environment.
findUp- Search for a file or directory by walking up from the start path within the workspace.
id- A unique identifier for this Workspace.
init- Initialize workspace config, creating dagger.toml.
install- Install a module into the workspace, writing dagger.toml to the host.
uninstall- Uninstall a module from the workspace, writing dagger.toml to the host.
changes- Return the changes from another workspace to this workspace.
checks- Return all checks from modules loaded in the workspace.
clientGenerate- Regenerate all generated API clients registered in workspace config and return the resulting Changeset.
clientInit- Plan the workspace changes for initializing a generated API client: generated client files at
pathplus a [[modules.<sdk-name>.as-sdk.clients]] entry in dagger.toml. Returns the resulting Changeset for the caller to preview and apply. 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.
moduleInit- Plan the workspace changes for initializing a new module: dagger-module.toml + SDK codegen output at
path, the authoring entry under [[modules.<sdk>.as-sdk.modules]], and (when path defaults) [modules.<name>]. The SDK must already be installed as an SDK. Returns the resulting Changeset for the caller to preview and apply. moduleList- List modules defined in the workspace configuration.
services- Return all services from modules loaded in the workspace.
update- Refresh workspace-managed state and return the resulting changeset.
withChanges- Return this workspace with a changeset applied, 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.
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.
configWrite(key: String!,value: String!,here: Boolean = false): String!
Write a configuration value to dagger.toml.
key: String!Dotted key path (e.g. modules.greeter.source).
value: String!Value to set. Bools, integers, and comma-separated arrays are auto-detected.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
cwd: String!
Current location within the workspace root.
The workspace root is returned as "/".
Relative paths in workspace APIs resolve from here.
envCreate(name: String!, here: Boolean = false): String!
Create a named workspace environment if it does not already exist.
name: String!Environment name.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
envList: [String!]!
List named environments defined in the workspace configuration.
envRemove(name: String!, here: Boolean = false): String!
Remove a named workspace environment.
name: String!Environment name.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
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.
id: ID!
A unique identifier for this Workspace.
init(here: Boolean = false): String!
Initialize workspace config, creating dagger.toml.
here: Boolean = falseCreate the workspace config directory at the workspace cwd instead of using the default write target.
install(ref: String!,name: String = "",here: Boolean = false,asSdk: Boolean = false,asSdkName: String = ""): String!
Install a module into the workspace, writing dagger.toml to the host.
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.
asSdk: Boolean = falseMark the install as an SDK (writes the
[modules.<name>.as-sdk]marker that dispatchesdagger module init <sdk>anddagger api client init <sdk>).asSdkName: String = ""User-facing SDK name to persist under
[modules.<name>.as-sdk] name = ....
uninstall(name: String!, here: Boolean = false): String!
Uninstall a module from the workspace, writing dagger.toml to the host.
name: String!Name of the installed module entry to remove.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
changes(other: Workspace!): Changeset!
Return the changes from another workspace to this workspace.
other: Workspace!Workspace to compare from.
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
clientGenerate: Changeset!
Regenerate all generated API clients registered in workspace config and return the resulting Changeset.
clientInit(path: String!,sdk: String!,module: String!,here: Boolean = false,args: JSON): Changeset!
Plan the workspace changes for initializing a generated API client: generated client files at path plus a [[modules.<sdk-name>.as-sdk.clients]] entry in dagger.toml. Returns the resulting Changeset for the caller to preview and apply.
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.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
args: JSON
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.
moduleInit(name: String!,sdk: String = "",path: String = "",source: String = "",include: [String!] = [],here: Boolean = false,args: JSON): Changeset!
Plan the workspace changes for initializing a new module: dagger-module.toml + SDK codegen output at path, the authoring entry under [[modules.<sdk>.as-sdk.modules]], and (when path defaults) [modules.<name>]. The SDK must already be installed as an SDK. Returns the resulting Changeset for the caller to preview and apply.
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. Defaults to ".dagger/modules/<name>"; using the default also installs the module in [modules.<name>].
source: String = ""Source subpath within the new module.
include: [String!] = []Additional include patterns for the module.
here: Boolean = falseWrite to the workspace config directory at the workspace cwd.
args: JSON
moduleList(module: String = ""): [WorkspaceModule!]!
List modules defined in the workspace configuration.
module: String = ""Optional module alias to inspect.
services(include: [String!]): UpGroup!
Return all services from modules loaded in the workspace.
include: [String!]Only include services matching the specified patterns
update: Changeset!Experimental
Refresh workspace-managed state and return the resulting changeset.
Currently this refreshes existing lockfile entries only.
Experimental: Experimental workspace update API currently refreshes existing lockfile entries only.
withChanges(changes: Changeset!): Workspace!
Return this workspace with a changeset applied, without mutating the source.
changes: Changeset!Changes to apply.
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.
References
Returned by
Binding.asWorkspaceDirectory.asWorkspaceGitRef.asWorkspaceGitRepository.asWorkspaceQuery.currentWorkspace