@spec address(t()) :: {:ok, String.t()} | {:error, term()}

Canonical Dagger address of the workspace location, or an opaque identity for synthetic workspaces.

@spec agents(t(), [{:include, [String.t()]}]) :: Dagger.AgentGroup.t()

Return all agent middlewares from modules loaded in the workspace.

@spec changes(t(), [{:from, t() | nil}]) :: Dagger.Changeset.t()

Return this workspace's changes, with paths relative to its working directory.

Pass from to compare against an earlier workspace state. Omitting it preserves the cumulative behavior used by clients from before this argument was added.

@spec checks(t(),
  include: [String.t()],
  skip: [String.t()],
  no_generate: boolean() | nil,
  only_generate: boolean() | nil
) :: Dagger.CheckGroup.t()

Return all checks from modules loaded in the workspace.

@spec config_file(t()) :: {:ok, String.t()} | {:error, term()}

Selected native workspace config file relative to the workspace cwd, if any.

@spec config_read(t(), [{:key, String.t() | nil}]) ::
  {:ok, String.t()} | {:error, term()}

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.

@spec cwd(t()) :: {:ok, String.t()} | {:error, term()}

Current location within the workspace root.

The workspace root is returned as "/".

Relative paths in workspace APIs resolve from here.

@spec detect_scope(t(), String.t()) :: {:ok, String.t()} | {:error, term()}

Return the selected SDK module's current scope at this workspace location.

@spec directory(t(), String.t(),
  exclude: [String.t()],
  include: [String.t()],
  gitignore: boolean() | nil
) :: Dagger.Directory.t()

Returns a Directory from the workspace.

Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.

@spec entrypoint(t()) :: {:ok, String.t()} | {:error, term()}

Installed name of the module selected as the workspace entrypoint, or an empty string when none is selected.

Reflects the selected env's effective view. Fails if several modules are selected.

@spec env_list(t()) :: {:ok, [String.t()]} | {:error, term()}

List named environments defined in the workspace configuration.

@spec export(t()) :: :ok | {:error, term()}

Write this workspace's pending changes to its local Git workspace on the current client's host.

Like Directory.export, the write is a side effect on the client that makes the call — never on the client that created the workspace. Inside a module, this cannot reach the caller's host.

@spec file(t(), String.t()) :: Dagger.File.t()

Returns a File from the workspace.

Relative paths resolve from the workspace cwd. Absolute paths resolve from the workspace root.

@spec find_roots(t(), [String.t()], start: String.t() | nil, exclude: [String.t()]) ::
  {:ok, [String.t()]} | {:error, term()}

Find project roots marked by any of the given filenames, starting from a path relative to the workspace cwd.

Returns cwd-relative directory paths for every marked directory at or below start, plus the nearest marked ancestor when start itself is not marked.

Each returned path is usable as-is with other workspace APIs, e.g. directory(path).

@spec find_up(t(), String.t(), [{:from, String.t() | nil}]) ::
  {:ok, String.t() | nil} | {:error, term()}

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.

@spec generators(t(), [{:include, [String.t()]}]) :: Dagger.GeneratorGroup.t()

Return all generators from modules loaded in the workspace.

@spec git(t()) :: Dagger.WorkspaceGit.t()

Git state for this workspace. Errors if the workspace is not in a git repository.

@spec glob(t(), String.t()) :: {:ok, [String.t()]} | {:error, term()}

Returns a list of files and directories that match the given pattern.

Patterns match paths relative to the workspace root.

@spec id(t()) :: {:ok, String.t()} | {:error, term()}

A unique identifier for this Workspace.

@spec migrate(t(), [{:modules, [String.t()]}]) :: Dagger.WorkspaceMigration.t()

Plan the explicit migration needed for the current workspace.

Include installed local modules and their local dependencies. Other module candidates remain unchanged unless selected.

The returned plan has an empty changeset and no steps when no migration is needed.

@spec migrate_module(t(), [{:path, String.t() | nil}]) ::
  Dagger.WorkspaceMigration.t()

Plan migration of one local module without migrating its dependencies or creating a workspace configuration.

Include SDK registration when a workspace configuration exists and remove obsolete generated-file ignore rules.

@spec module(t(), String.t()) :: Dagger.WorkspaceModule.t()

Return a module defined in the workspace configuration.

Reflects the selected env's effective view.

@spec module_source(t(), String.t()) :: Dagger.ModuleSource.t()

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.

@spec modules(t()) :: {:ok, [Dagger.WorkspaceModule.t()]} | {:error, term()}

List modules defined in the workspace configuration.

Reflects the selected env's effective view.

@spec reloaded(t()) :: t()

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.

@spec sdk(t(), String.t()) :: Dagger.WorkspaceSDK.t()

An installed SDK, by name.

@spec sdks(t()) :: {:ok, [Dagger.WorkspaceSDK.t()]} | {:error, term()}

Installed SDKs.

@spec search(t(), String.t(),
  paths: [String.t()],
  globs: [String.t()],
  literal: boolean() | nil,
  multiline: boolean() | nil,
  dotall: boolean() | nil,
  insensitive: boolean() | nil,
  skip_ignored: boolean() | nil,
  skip_hidden: boolean() | nil,
  files_only: boolean() | nil,
  limit: integer() | nil
) :: {:ok, [Dagger.SearchResult.t()]} | {:error, term()}

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.

@spec services(t(), [{:include, [String.t()]}]) :: Dagger.UpGroup.t()

Return all services from modules loaded in the workspace.

@spec terminals(t(), [{:include, [String.t()]}]) :: Dagger.TerminalGroup.t()

Return all terminal targets from modules loaded in the workspace.

@spec with_changes(t(), Dagger.Changeset.t()) :: t()

Return this workspace with a changeset applied, without mutating the source.

@spec with_client(t(), String.t(),
  sdk: String.t() | nil,
  settings: Dagger.JSON.t() | nil
) :: t()

Return this workspace with a generated module client added to one SDK scope.

Select the deepest detected or registered scope. Fail if several SDKs have that deepest scope.

@spec with_config_env(t(), String.t(), [{:here, boolean() | nil}]) :: t()

Return this workspace with a named config environment created.

@spec with_config_value(t(), String.t(), String.t(),
  values: [String.t()],
  here: boolean() | nil
) :: t()

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.

@spec with_directory(t(), String.t(), Dagger.Directory.t()) :: t()

Return this workspace with a directory merged into the given path, without mutating the source.

Anything already at the path stays, and files the source carries win, as with Directory.withDirectory. Use withNewDirectory to replace the path instead.

@spec with_entrypoint(t(), String.t()) :: t()

Return this workspace with an installed module selected as its entrypoint.

Every other entrypoint selection is cleared. Entrypoints live in the base workspace config.

@spec with_file(t(), String.t(), Dagger.File.t(), [{:permissions, integer() | nil}]) ::
  t()

Return this workspace with a file added or replaced, without mutating the source.

@spec with_init_module(t(), String.t(),
  name: String.t() | nil,
  path: String.t() | nil,
  install: boolean() | nil,
  entrypoint: boolean() | nil,
  settings: Dagger.JSON.t() | nil
) :: t()

Return this workspace with a location initialized as a module scope.

The selected SDK module records the scope and generates the module source.

@spec with_initialized(t()) :: t()

Return this workspace with a native configuration, without changing an existing configuration.

Fail if legacy configuration needs workspace migration.

@spec with_module(t(), String.t(), name: String.t() | nil, here: boolean() | nil) ::
  t()

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.

@spec with_mounted_directory(t(), String.t(), Dagger.Directory.t()) :: t()

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.

@spec with_mounted_file(t(), String.t(), Dagger.File.t()) :: t()

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.

@spec with_new_directory(t(), String.t(), Dagger.Directory.t()) :: t()

Return this workspace with the given path replaced by a directory, without mutating the source.

The source becomes the entire contents of the path: anything already there that the source does not carry is removed. Use withDirectory to keep it instead.

@spec with_new_file(t(), String.t(), String.t(), [{:permissions, integer() | nil}]) ::
  t()

Return this workspace with a new or replaced file, without mutating the source.

@spec with_sdk(t(), String.t(),
  name: String.t() | nil,
  here: boolean() | nil,
  as_sdk_name: String.t() | nil
) :: t()

Return this workspace with an SDK installed in its config.

@spec with_updated_clients(t(),
  modules: [String.t()],
  all: boolean() | nil,
  sdk: String.t() | nil
) ::
  t()

Return this workspace with the selected module clients updated.

The engine re-reads the source of each selected client target and writes the lock entries that those targets reach.

The selected SDK module then regenerates every scope that owns one of the targets.

@spec with_updated_lock(t(), [{:no_generate, boolean() | nil}]) :: t()

Return this workspace with refreshed lockfile state.

SDK client scopes are regenerated unless noGenerate is true.

@spec with_updated_modules(t(), names: [String.t()], version: String.t() | nil) :: t()

Return this workspace with updated module versions and lockfile state.

An SDK client scope is regenerated when it targets an updated module.

@spec with_workdir(t(), String.t()) :: t()

Return this workspace with its working directory pointed at the given workspace-relative path.

@spec without_client(t(), String.t(), [{:sdk, String.t() | nil}]) :: t()

Return this workspace with a module client removed from the deepest matching recorded scope.

Fail if several SDKs have that deepest scope. The selected SDK module regenerates the complete scope.

If invalid client targets remain, save the removal and skip generation until those targets are corrected or removed.

@spec without_config_env(t(), String.t(), [{:here, boolean() | nil}]) :: t()

Return this workspace with a named config environment removed.

@spec without_config_value(t(), String.t(), [{:here, boolean() | nil}]) :: t()

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.

@spec without_directory(t(), String.t()) :: t()

Return this workspace with a directory removed, without mutating the source.

@spec without_entrypoint(t()) :: t()

Return this workspace with no module selected as its entrypoint.

@spec without_file(t(), String.t()) :: t()

Return this workspace with a file removed, without mutating the source.

@spec without_module(t(), String.t(), [{:here, boolean() | nil}]) :: t()

Return this workspace with a module removed from its config.

When the session selects an env, only that env's overlay entry is removed.

@spec without_sdk(t(), String.t(), [{:here, boolean() | nil}]) :: t()

Return this workspace with an SDK removed from its config.