Class: Workspace
A Dagger workspace detected from the current working directory or constructed from a Directory.
Extends
BaseClient
Constructors
Constructor
new Workspace(
ctx?,_id?,_address?,_configFile?,_configRead?,_configWrite?,_cwd?,_envCreate?,_envRemove?,_findUp?,_init?,_install?,_uninstall?):Workspace
Constructor is used for internal usage only, do not create object from it.
Parameters
ctx?
Context
_id?
_address?
string
_configFile?
string
_configRead?
string
_configWrite?
string
_cwd?
string
_envCreate?
string
_envRemove?
string
_findUp?
string
_init?
string
_install?
string
_uninstall?
string
Returns
Workspace
Overrides
BaseClient.constructor
Methods
address()
address():
Promise<string>
Canonical Dagger address of the workspace location, or an opaque identity for synthetic workspaces.
Returns
Promise<string>
changes()
changes(
other):Changeset
Return the changes from another workspace to this workspace.
Parameters
other
Workspace
Workspace to compare from.
Returns
checks()
checks(
opts?):CheckGroup
Return all checks from modules loaded in the workspace.
Parameters
opts?
Returns
clientGenerate()
clientGenerate():
Changeset
Regenerate all generated API clients registered in workspace config and return the resulting Changeset.
Returns
clientInit()
clientInit(
path,sdk,module_,opts?):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.
Parameters
path
string
Workspace-relative output directory for the generated client.
sdk
string
Workspace SDK name or module entry name to use.
module_
string
opts?
Returns
configFile()
configFile():
Promise<string>
Selected native workspace config file relative to the workspace root, if any.
Returns
Promise<string>
configRead()
configRead(
opts?):Promise<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.
Parameters
opts?
Returns
Promise<string>
configWrite()
configWrite(
key,value,opts?):Promise<string>
Write a configuration value to dagger.toml.
Parameters
key
string
Dotted key path (e.g. modules.greeter.source).
value
string
Value to set. Bools, integers, and comma-separated arrays are auto-detected.
opts?
Returns
Promise<string>
cwd()
cwd():
Promise<string>
Current location within the workspace root.
The workspace root is returned as "/".
Relative paths in workspace APIs resolve from here.
Returns
Promise<string>
directory()
directory(
path,opts?):Directory
Returns a Directory from the workspace.
Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.
Parameters
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.
opts?
Returns
envCreate()
envCreate(
name,opts?):Promise<string>
Create a named workspace environment if it does not already exist.
Parameters
name
string
Environment name.
opts?
Returns
Promise<string>
envList()
envList():
Promise<string[]>
List named environments defined in the workspace configuration.
Returns
Promise<string[]>
envRemove()
envRemove(
name,opts?):Promise<string>
Remove a named workspace environment.
Parameters
name
string
Environment name.
opts?
Returns
Promise<string>
file()
file(
path):File
Returns a File from the workspace.
Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.
Parameters
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.
Returns
findUp()
findUp(
name,opts?):Promise<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.
Parameters
name
string
The name of the file or directory to search for.
opts?
Returns
Promise<string>
generators()
generators(
opts?):GeneratorGroup
Return all generators from modules loaded in the workspace.
Parameters
opts?
Returns
git()
git():
WorkspaceGit
Git state for this workspace. Errors if the workspace is not in a git repository.
Returns
id()
id():
Promise<ID>
A unique identifier for this Workspace.
Returns
Promise<ID>
init()
init(
opts?):Promise<string>
Initialize workspace config, creating dagger.toml.
Parameters
opts?
Returns
Promise<string>
install()
install(
ref,opts?):Promise<string>
Install a module into the workspace, writing dagger.toml to the host.
Parameters
ref
string
Module reference to install.
opts?
Returns
Promise<string>
migrate()
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.
Returns
moduleInit()
moduleInit(
name,opts?):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.
Parameters
name
string
Name of the new module.
opts?
Returns
moduleList()
moduleList(
opts?):Promise<WorkspaceModule[]>
List modules defined in the workspace configuration.
Parameters
opts?
Returns
Promise<WorkspaceModule[]>
services()
services(
opts?):UpGroup
Return all services from modules loaded in the workspace.
Parameters
opts?
Returns
uninstall()
uninstall(
name,opts?):Promise<string>
Uninstall a module from the workspace, writing dagger.toml to the host.
Parameters
name
string
Name of the installed module entry to remove.
opts?
Returns
Promise<string>
update()
update():
Changeset
Experimental
Refresh workspace-managed state and return the resulting changeset.
Currently this refreshes existing lockfile entries only.
Returns
with()
with(
arg):Workspace
Call the provided function with current Workspace.
This is useful for reusability and readability by not breaking the calling chain.
Parameters
arg
(param) => Workspace
Returns
Workspace
withChanges()
withChanges(
changes):Workspace
Return this workspace with a changeset applied, without mutating the source.
Parameters
changes
Changes to apply.
Returns
Workspace
withNewDirectory()
withNewDirectory(
path,source):Workspace
Return this workspace with a directory added, without mutating the source.
Parameters
path
string
Path of the added directory. Relative paths resolve from the workspace cwd.
source
Directory to add.
Returns
Workspace
withNewFile()
withNewFile(
path,contents,opts?):Workspace
Return this workspace with a new or replaced file, without mutating the source.
Parameters
path
string
Path of the new file. Relative paths resolve from the workspace cwd.
contents
string
Contents of the new file.
opts?
Returns
Workspace