@dagger.io/dagger 0.18.1 → 0.18.3

package/dist/src/api/client.gen.d.ts

@@ -126,6 +126,12 @@ export type ContainerBuildOpts = {
      * They can be accessed in the Dockerfile using the "secret" mount type and mount path /run/secrets/[secret-name], e.g. RUN --mount=type=secret,id=my-secret curl [http://example.com?token=$(cat /run/secrets/my-secret)](http://example.com?token=$(cat /run/secrets/my-secret))
      */
     secrets?: Secret[];
+    /**
+     * If set, skip the automatic init process injected into containers created by RUN statements.
+     *
+     * This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
+     */
+    noInit?: boolean;
 };
 export type ContainerDirectoryOpts = {
     /**
@@ -185,7 +191,7 @@ export type ContainerPublishOpts = {
     /**
      * Use the specified media types for the published image's layers.
      *
-     * Defaults to OCI, which is largely compatible with most recent registries, but Docker may be needed for older registries without OCI support.
+     * Defaults to "OCI", which is compatible with most recent registries, but "Docker" may be needed for older registries without OCI support.
      */
     mediaTypes?: ImageMediaTypes;
 };
@@ -283,7 +289,7 @@ export type ContainerWithDirectoryOpts = {
 };
 export type ContainerWithEntrypointOpts = {
     /**
-     * Don't remove the default arguments when setting the entrypoint.
+     * Don't reset the default arguments when setting the entrypoint. By default it is reset, since entrypoint and default args are often tightly coupled.
      */
     keepDefaultArgs?: boolean;
 };
@@ -295,19 +301,19 @@ export type ContainerWithEnvVariableOpts = {
 };
 export type ContainerWithExecOpts = {
     /**
-     * If the container has an entrypoint, prepend it to the args.
+     * Apply the OCI entrypoint, if present, by prepending it to the args. Ignored by default.
      */
     useEntrypoint?: boolean;
     /**
-     * Content to write to the command's standard input before closing (e.g., "Hello world").
+     * Content to write to the command's standard input. Example: "Hello world")
      */
     stdin?: string;
     /**
-     * Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
+     * Redirect the command's standard output to a file in the container. Example: "./stdout.txt"
      */
     redirectStdout?: string;
     /**
-     * Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
+     * Like redirectStdout, but for standard error
      */
     redirectStderr?: string;
     /**
@@ -316,12 +322,12 @@ export type ContainerWithExecOpts = {
     expect?: ReturnType;
     /**
      * Provides Dagger access to the executed command.
-     *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      */
     experimentalPrivilegedNesting?: boolean;
     /**
-     * Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
+     * Execute the command with all root capabilities. Like --privileged in Docker
+     *
+     * DANGER: this grants the command full access to the host system. Only use when 1) you trust the command being executed and 2) you specifically need this level of access.
      */
     insecureRootCapabilities?: boolean;
     /**
@@ -329,19 +335,19 @@ export type ContainerWithExecOpts = {
      */
     expand?: boolean;
     /**
-     * If set, skip the automatic init process injected into containers by default.
+     * Skip the automatic init process injected into containers by default.
      *
-     * This should only be used if the user requires that their exec process be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
+     * Only use this if you specifically need the command to be pid 1 in the container. Otherwise it may result in unexpected behavior. If you're not sure, you don't need this.
      */
     noInit?: boolean;
 };
 export type ContainerWithExposedPortOpts = {
     /**
-     * Transport layer network protocol
+     * Network protocol. Example: "tcp"
      */
     protocol?: NetworkProtocol;
     /**
-     * Optional port description
+     * Port description. Example: "payment API endpoint"
      */
     description?: string;
     /**
@@ -351,7 +357,7 @@ export type ContainerWithExposedPortOpts = {
 };
 export type ContainerWithFileOpts = {
     /**
-     * Permission given to the copied file (e.g., 0600).
+     * Permissions of the new file. Example: 0600
      */
     permissions?: number;
     /**
@@ -469,7 +475,7 @@ export type ContainerWithMountedTempOpts = {
 };
 export type ContainerWithNewFileOpts = {
     /**
-     * Permission given to the written file (e.g., 0600).
+     * Permissions of the new file. Example: 0600
      */
     permissions?: number;
     /**
@@ -608,6 +614,12 @@ export type DirectoryDockerBuildOpts = {
      * They will be mounted at /run/secrets/[secret-name].
      */
     secrets?: Secret[];
+    /**
+     * If set, skip the automatic init process injected into containers created by RUN statements.
+     *
+     * This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
+     */
+    noInit?: boolean;
 };
 export type DirectoryEntriesOpts = {
     /**
@@ -623,11 +635,11 @@ export type DirectoryExportOpts = {
 };
 export type DirectoryFilterOpts = {
     /**
-     * Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
+     * If set, paths matching one of these glob patterns is excluded from the new snapshot. Example: ["node_modules/", ".git*", ".env"]
      */
     exclude?: string[];
     /**
-     * Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
+     * If set, only paths matching one of these glob patterns is included in the new snapshot. Example: (e.g., ["app/", "package.*"]).
      */
     include?: string[];
 };
@@ -681,7 +693,7 @@ export type DirectoryWithNewDirectoryOpts = {
 };
 export type DirectoryWithNewFileOpts = {
     /**
-     * Permission given to the copied file (e.g., 0600).
+     * Permissions of the new file. Example: 0600
      */
     permissions?: number;
 };
@@ -1045,10 +1057,16 @@ export type ClientCacheVolumeOpts = {
 };
 export type ClientContainerOpts = {
     /**
-     * Platform to initialize the container with.
+     * Platform to initialize the container with. Defaults to the native platform of the current engine
      */
     platform?: Platform;
 };
+export type ClientEnvOpts = {
+    /**
+     * Give the environment the same privileges as the caller: core API including host access, current module, and dependencies
+     */
+    privileged?: boolean;
+};
 export type ClientGitOpts = {
     /**
      * DEPRECATED: Set to true to keep .git directory.
@@ -1083,9 +1101,6 @@ export type ClientLlmOpts = {
      */
     maxAPICalls?: number;
 };
-export type ClientLoadSecretFromNameOpts = {
-    accessor?: string;
-};
 export type ClientModuleSourceOpts = {
     /**
      * The pinned version of the module source
@@ -1452,7 +1467,7 @@ export declare class Container extends BaseClient {
      */
     asService: (opts?: ContainerAsServiceOpts) => Service;
     /**
-     * Returns a File representing the container serialized to a tarball.
+     * Package the container state as an OCI image, and return it as a tar archive
      * @param opts.platformVariants Identifiers for other platform specific containers.
      *
      * Used for multi-platform images.
@@ -1475,14 +1490,17 @@ export declare class Container extends BaseClient {
      * They will be mounted at /run/secrets/[secret-name] in the build container
      *
      * They can be accessed in the Dockerfile using the "secret" mount type and mount path /run/secrets/[secret-name], e.g. RUN --mount=type=secret,id=my-secret curl [http://example.com?token=$(cat /run/secrets/my-secret)](http://example.com?token=$(cat /run/secrets/my-secret))
+     * @param opts.noInit If set, skip the automatic init process injected into containers created by RUN statements.
+     *
+     * This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
      */
     build: (context: Directory, opts?: ContainerBuildOpts) => Container;
     /**
-     * Retrieves default arguments for future commands.
+     * Return the container's default arguments.
      */
     defaultArgs: () => Promise<string[]>;
     /**
-     * Retrieves a directory at the given path.
+     * Retrieve a directory from the container's root filesystem
      *
      * Mounts are included.
      * @param path The path of the directory to retrieve (e.g., "./src").
@@ -1490,7 +1508,7 @@ export declare class Container extends BaseClient {
      */
     directory: (path: string, opts?: ContainerDirectoryOpts) => Directory;
     /**
-     * Retrieves entrypoint to be prepended to the arguments of all commands.
+     * Return the container's OCI entrypoint.
      */
     entrypoint: () => Promise<string[]>;
     /**
@@ -1503,9 +1521,9 @@ export declare class Container extends BaseClient {
      */
     envVariables: () => Promise<EnvVariable[]>;
     /**
-     * The exit code of the last executed command.
+     * The exit code of the last executed command
      *
-     * Returns an error if no command was set.
+     * Returns an error if no command was executed
      */
     exitCode: () => Promise<number>;
     /**
@@ -1559,10 +1577,8 @@ export declare class Container extends BaseClient {
      */
     file: (path: string, opts?: ContainerFileOpts) => File;
     /**
-     * Initializes this container from a pulled base image.
-     * @param address Image's address from its registry.
-     *
-     * Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").
+     * Download a container image, and apply it to the container state. All previous state will be lost.
+     * @param address Address of the container image to download, in standard OCI ref format. Example:"registry.dagger.io/engine:latest"
      */
     from: (address: string) => Container;
     /**
@@ -1593,14 +1609,12 @@ export declare class Container extends BaseClient {
      */
     platform: () => Promise<Platform>;
     /**
-     * Publishes this container as a new image to the specified address.
+     * Package the container state as an OCI image, and publish it to a registry
      *
-     * Publish returns a fully qualified ref.
+     * Returns the fully qualified address of the published image, with digest
+     * @param address The OCI address to publish to
      *
-     * It can also publish platform variants.
-     * @param address Registry's address to publish the image to.
-     *
-     * Formatted as [host]/[user]/[repo]:[tag] (e.g. "docker.io/dagger/dagger:main").
+     * Same format as "docker push". Example: "registry.example.com/user/repo:tag"
      * @param opts.platformVariants Identifiers for other platform specific containers.
      *
      * Used for multi-platform image.
@@ -1609,23 +1623,23 @@ export declare class Container extends BaseClient {
      * If this is unset, then if a layer already has a compressed blob in the engine's cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine's cache, then it will be compressed using Gzip.
      * @param opts.mediaTypes Use the specified media types for the published image's layers.
      *
-     * Defaults to OCI, which is largely compatible with most recent registries, but Docker may be needed for older registries without OCI support.
+     * Defaults to "OCI", which is compatible with most recent registries, but "Docker" may be needed for older registries without OCI support.
      */
     publish: (address: string, opts?: ContainerPublishOpts) => Promise<string>;
     /**
-     * Retrieves this container's root filesystem. Mounts are not included.
+     * Return a snapshot of the container's root filesystem. The snapshot can be modified then written back using withRootfs. Use that method for filesystem modifications.
      */
     rootfs: () => Directory;
     /**
-     * The error stream of the last executed command.
+     * The buffered standard error stream of the last executed command
      *
-     * Returns an error if no command was set.
+     * Returns an error if no command was executed
      */
     stderr: () => Promise<string>;
     /**
-     * The output stream of the last executed command.
+     * The buffered standard output stream of the last executed command
      *
-     * Returns an error if no command was set.
+     * Returns an error if no command was executed
      */
     stdout: () => Promise<string>;
     /**
@@ -1676,7 +1690,7 @@ export declare class Container extends BaseClient {
      */
     withAnnotation: (name: string, value: string) => Container;
     /**
-     * Configures default arguments for future commands.
+     * Configures default arguments for future commands. Like CMD in Dockerfile.
      * @param args Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).
      */
     withDefaultArgs: (args: string[]) => Container;
@@ -1690,7 +1704,7 @@ export declare class Container extends BaseClient {
      */
     withDefaultTerminalCmd: (args: string[], opts?: ContainerWithDefaultTerminalCmdOpts) => Container;
     /**
-     * Retrieves this container plus a directory written at the given path.
+     * Return a new container snapshot, with a directory added to its filesystem
      * @param path Location of the written directory (e.g., "/tmp/directory").
      * @param directory Identifier of the directory to write
      * @param opts.exclude Patterns to exclude in the written directory (e.g. ["node_modules/**", ".gitignore", ".git/"]).
@@ -1704,57 +1718,59 @@ export declare class Container extends BaseClient {
      */
     withDirectory: (path: string, directory: Directory, opts?: ContainerWithDirectoryOpts) => Container;
     /**
-     * Retrieves this container but with a different command entrypoint.
-     * @param args Entrypoint to use for future executions (e.g., ["go", "run"]).
-     * @param opts.keepDefaultArgs Don't remove the default arguments when setting the entrypoint.
+     * Set an OCI-style entrypoint. It will be included in the container's OCI configuration. Note, withExec ignores the entrypoint by default.
+     * @param args Arguments of the entrypoint. Example: ["go", "run"].
+     * @param opts.keepDefaultArgs Don't reset the default arguments when setting the entrypoint. By default it is reset, since entrypoint and default args are often tightly coupled.
      */
     withEntrypoint: (args: string[], opts?: ContainerWithEntrypointOpts) => Container;
     /**
-     * Retrieves this container plus the given environment variable.
-     * @param name The name of the environment variable (e.g., "HOST").
-     * @param value The value of the environment variable. (e.g., "localhost").
+     * Set a new environment variable in the container.
+     * @param name Name of the environment variable (e.g., "HOST").
+     * @param value Value of the environment variable. (e.g., "localhost").
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value according to the current environment variables defined in the container (e.g. "/opt/bin:$PATH").
      */
     withEnvVariable: (name: string, value: string, opts?: ContainerWithEnvVariableOpts) => Container;
     /**
-     * Retrieves this container after executing the specified command inside it.
-     * @param args Command to run instead of the container's default command (e.g., ["go", "run", "main.go"]).
+     * Execute a command in the container, and return a new snapshot of the container state after execution.
+     * @param args Command to execute. Must be valid exec() arguments, not a shell command. Example: ["go", "run", "main.go"].
      *
-     * If empty, the container's default command is used.
-     * @param opts.useEntrypoint If the container has an entrypoint, prepend it to the args.
-     * @param opts.stdin Content to write to the command's standard input before closing (e.g., "Hello world").
-     * @param opts.redirectStdout Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
-     * @param opts.redirectStderr Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
+     * To run a shell command, execute the shell and pass the shell command as argument. Example: ["sh", "-c", "ls -l | grep foo"]
+     *
+     * Defaults to the container's default arguments (see "defaultArgs" and "withDefaultArgs").
+     * @param opts.useEntrypoint Apply the OCI entrypoint, if present, by prepending it to the args. Ignored by default.
+     * @param opts.stdin Content to write to the command's standard input. Example: "Hello world")
+     * @param opts.redirectStdout Redirect the command's standard output to a file in the container. Example: "./stdout.txt"
+     * @param opts.redirectStderr Like redirectStdout, but for standard error
      * @param opts.expect Exit codes this command is allowed to exit with without error
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
+     * @param opts.insecureRootCapabilities Execute the command with all root capabilities. Like --privileged in Docker
      *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
-     * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
+     * DANGER: this grants the command full access to the host system. Only use when 1) you trust the command being executed and 2) you specifically need this level of access.
      * @param opts.expand Replace "${VAR}" or "$VAR" in the args according to the current environment variables defined in the container (e.g. "/$VAR/foo").
-     * @param opts.noInit If set, skip the automatic init process injected into containers by default.
+     * @param opts.noInit Skip the automatic init process injected into containers by default.
      *
-     * This should only be used if the user requires that their exec process be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
+     * Only use this if you specifically need the command to be pid 1 in the container. Otherwise it may result in unexpected behavior. If you're not sure, you don't need this.
      */
     withExec: (args: string[], opts?: ContainerWithExecOpts) => Container;
     /**
-     * Expose a network port.
+     * Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support)
      *
      * Exposed ports serve two purposes:
      *
      * - For health checks and introspection, when running services
      *
      * - For setting the EXPOSE OCI field when publishing the container
-     * @param port Port number to expose
-     * @param opts.protocol Transport layer network protocol
-     * @param opts.description Optional port description
+     * @param port Port number to expose. Example: 8080
+     * @param opts.protocol Network protocol. Example: "tcp"
+     * @param opts.description Port description. Example: "payment API endpoint"
      * @param opts.experimentalSkipHealthcheck Skip the health check when run as a service.
      */
     withExposedPort: (port: number, opts?: ContainerWithExposedPortOpts) => Container;
     /**
-     * Retrieves this container plus the contents of the given file copied to the given path.
-     * @param path Location of the copied file (e.g., "/tmp/file.txt").
-     * @param source Identifier of the file to copy.
-     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     * Return a container snapshot with a file added
+     * @param path Path of the new file. Example: "/path/to/new-file.txt"
+     * @param source File to add
+     * @param opts.permissions Permissions of the new file. Example: 0600
      * @param opts.owner A user:group to set for the file.
      *
      * The user and group can either be an ID (1000:1000) or a name (foo:bar).
@@ -1845,10 +1861,10 @@ export declare class Container extends BaseClient {
      */
     withMountedTemp: (path: string, opts?: ContainerWithMountedTempOpts) => Container;
     /**
-     * Retrieves this container plus a new file written at the given path.
-     * @param path Location of the written file (e.g., "/tmp/file.txt").
-     * @param contents Content of the file to write (e.g., "Hello world!").
-     * @param opts.permissions Permission given to the written file (e.g., 0600).
+     * Return a new container snapshot, with a file added to its filesystem
+     * @param path Path of the new file. May be relative or absolute. Example: "README.md" or "/etc/profile"
+     * @param contents Contents of the new file. Example: "Hello world!"
+     * @param opts.permissions Permissions of the new file. Example: 0600
      * @param opts.owner A user:group to set for the file.
      *
      * The user and group can either be an ID (1000:1000) or a name (foo:bar).
@@ -1858,35 +1874,33 @@ export declare class Container extends BaseClient {
      */
     withNewFile: (path: string, contents: string, opts?: ContainerWithNewFileOpts) => Container;
     /**
-     * Retrieves this container with a registry authentication for a given address.
-     * @param address Registry's address to bind the authentication to.
-     *
-     * Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
-     * @param username The username of the registry's account (e.g., "Dagger").
-     * @param secret The API key, password or token to authenticate to this registry.
+     * Attach credentials for future publishing to a registry. Use in combination with publish
+     * @param address The image address that needs authentication. Same format as "docker push". Example: "registry.dagger.io/dagger:latest"
+     * @param username The username to authenticate with. Example: "alice"
+     * @param secret The API key, password or token to authenticate to this registry
      */
     withRegistryAuth: (address: string, username: string, secret: Secret) => Container;
     /**
-     * Retrieves the container with the given directory mounted to /.
-     * @param directory Directory to mount.
+     * Change the container's root filesystem. The previous root filesystem will be lost.
+     * @param directory The new root filesystem.
      */
     withRootfs: (directory: Directory) => Container;
     /**
-     * Retrieves this container plus an env variable containing the given secret.
-     * @param name The name of the secret variable (e.g., "API_SECRET").
-     * @param secret The identifier of the secret value.
+     * Set a new environment variable, using a secret value
+     * @param name Name of the secret variable (e.g., "API_SECRET").
+     * @param secret Identifier of the secret value.
      */
     withSecretVariable: (name: string, secret: Secret) => Container;
     /**
-     * Establish a runtime dependency on a service.
+     * Establish a runtime dependency on a from a container to a network service.
      *
      * The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.
      *
      * The service will be reachable from the container via the provided hostname alias.
      *
      * The service dependency will also convey to any files or directories produced by the container.
-     * @param alias A name that can be used to reach the service from the container
-     * @param service Identifier of the service container
+     * @param alias Hostname that will resolve to the target service (only accessible from within this container)
+     * @param service The target service
      */
     withServiceBinding: (alias: string, service: Service) => Container;
     /**
@@ -1907,7 +1921,7 @@ export declare class Container extends BaseClient {
      */
     withUser: (name: string) => Container;
     /**
-     * Retrieves this container with a different working directory.
+     * Change the container's working directory. Like WORKDIR in Dockerfile.
      * @param path The path to set as the working directory (e.g., "/app").
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value of path according to the current environment variables defined in the container (e.g. "/$VAR/foo").
      */
@@ -1918,17 +1932,17 @@ export declare class Container extends BaseClient {
      */
     withoutAnnotation: (name: string) => Container;
     /**
-     * Retrieves this container with unset default arguments for future commands.
+     * Remove the container's default arguments.
      */
     withoutDefaultArgs: () => Container;
     /**
-     * Retrieves this container with the directory at the given path removed.
+     * Return a new container snapshot, with a directory removed from its filesystem
      * @param path Location of the directory to remove (e.g., ".github/").
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value of path according to the current environment variables defined in the container (e.g. "/$VAR/foo").
      */
     withoutDirectory: (path: string, opts?: ContainerWithoutDirectoryOpts) => Container;
     /**
-     * Retrieves this container with an unset command entrypoint.
+     * Reset the container's OCI entrypoint.
      * @param opts.keepDefaultArgs Don't remove the default arguments when unsetting the entrypoint.
      */
     withoutEntrypoint: (opts?: ContainerWithoutEntrypointOpts) => Container;
@@ -1950,8 +1964,8 @@ export declare class Container extends BaseClient {
      */
     withoutFile: (path: string, opts?: ContainerWithoutFileOpts) => Container;
     /**
-     * Retrieves this container with the files at the given paths removed.
-     * @param paths Location of the files to remove (e.g., ["/file.txt"]).
+     * Return a new container spanshot with specified files removed
+     * @param paths Paths of the files to remove. Example: ["foo.txt, "/root/.ssh/config"
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value of paths according to the current environment variables defined in the container (e.g. "/$VAR/foo.txt").
      */
     withoutFiles: (paths: string[], opts?: ContainerWithoutFilesOpts) => Container;
@@ -1991,7 +2005,7 @@ export declare class Container extends BaseClient {
      */
     withoutUser: () => Container;
     /**
-     * Retrieves this container with an unset working directory.
+     * Unset the container's working directory.
      *
      * Should default to "/".
      */
@@ -2060,7 +2074,7 @@ export declare class Directory extends BaseClient {
      */
     id: () => Promise<DirectoryID>;
     /**
-     * Converts this directory into a git repository
+     * Converts this directory to a local git repository
      */
     asGit: () => GitRepository;
     /**
@@ -2078,8 +2092,8 @@ export declare class Directory extends BaseClient {
      */
     asModuleSource: (opts?: DirectoryAsModuleSourceOpts) => ModuleSource;
     /**
-     * Gets the difference between this directory and an another directory.
-     * @param other Identifier of the directory to compare.
+     * Return the difference between this directory and an another directory. The difference is encoded as a directory.
+     * @param other The directory to compare against
      */
     diff: (other: Directory) => Directory;
     /**
@@ -2088,11 +2102,11 @@ export declare class Directory extends BaseClient {
     digest: () => Promise<string>;
     /**
      * Retrieves a directory at the given path.
-     * @param path Location of the directory to retrieve (e.g., "/src").
+     * @param path Location of the directory to retrieve. Example: "/src"
      */
     directory: (path: string) => Directory;
     /**
-     * Builds a new Docker container from this directory.
+     * Use Dockerfile compatibility to build a container from this directory. Only use this function for Dockerfile compatibility. Otherwise use the native Container type directly, it is feature-complete and supports all Dockerfile features.
      * @param opts.platform The platform to build.
      * @param opts.dockerfile Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
      * @param opts.target Target build stage to build.
@@ -2100,6 +2114,9 @@ export declare class Directory extends BaseClient {
      * @param opts.secrets Secrets to pass to the build.
      *
      * They will be mounted at /run/secrets/[secret-name].
+     * @param opts.noInit If set, skip the automatic init process injected into containers created by RUN statements.
+     *
+     * This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
      */
     dockerBuild: (opts?: DirectoryDockerBuildOpts) => Container;
     /**
@@ -2114,14 +2131,14 @@ export declare class Directory extends BaseClient {
      */
     export: (path: string, opts?: DirectoryExportOpts) => Promise<string>;
     /**
-     * Retrieves a file at the given path.
+     * Retrieve a file at the given path.
      * @param path Location of the file to retrieve (e.g., "README.md").
      */
     file: (path: string) => File;
     /**
-     * Retrieves this directory as per exclude/include filters.
-     * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
-     * @param opts.include Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
+     * Return a snapshot with some paths included or excluded
+     * @param opts.exclude If set, paths matching one of these glob patterns is excluded from the new snapshot. Example: ["node_modules/", ".git*", ".env"]
+     * @param opts.include If set, only paths matching one of these glob patterns is included in the new snapshot. Example: (e.g., ["app/", "package.*"]).
      */
     filter: (opts?: DirectoryFilterOpts) => Directory;
     /**
@@ -2148,7 +2165,7 @@ export declare class Directory extends BaseClient {
      */
     terminal: (opts?: DirectoryTerminalOpts) => Directory;
     /**
-     * Retrieves this directory plus a directory written at the given path.
+     * Return a snapshot with a directory added
      * @param path Location of the written directory (e.g., "/src/").
      * @param directory Identifier of the directory to copy.
      * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
@@ -2176,10 +2193,10 @@ export declare class Directory extends BaseClient {
      */
     withNewDirectory: (path: string, opts?: DirectoryWithNewDirectoryOpts) => Directory;
     /**
-     * Retrieves this directory plus a new file written at the given path.
-     * @param path Location of the written file (e.g., "/file.txt").
-     * @param contents Content of the written file (e.g., "Hello world!").
-     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     * Return a snapshot with a new file added
+     * @param path Path of the new file. Example: "foo/bar.txt"
+     * @param contents Contents of the new file. Example: "Hello world!"
+     * @param opts.permissions Permissions of the new file. Example: 0600
      */
     withNewFile: (path: string, contents: string, opts?: DirectoryWithNewFileOpts) => Directory;
     /**
@@ -2190,18 +2207,18 @@ export declare class Directory extends BaseClient {
      */
     withTimestamps: (timestamp: number) => Directory;
     /**
-     * Retrieves this directory with the directory at the given path removed.
-     * @param path Location of the directory to remove (e.g., ".github/").
+     * Return a snapshot with a subdirectory removed
+     * @param path Path of the subdirectory to remove. Example: ".github/workflows"
      */
     withoutDirectory: (path: string) => Directory;
     /**
-     * Retrieves this directory with the file at the given path removed.
-     * @param path Location of the file to remove (e.g., "/file.txt").
+     * Return a snapshot with a file removed
+     * @param path Path of the file to remove (e.g., "/file.txt").
      */
     withoutFile: (path: string) => Directory;
     /**
-     * Retrieves this directory with the files at the given paths removed.
-     * @param paths Location of the file to remove (e.g., ["/file.txt"]).
+     * Return a snapshot with files removed
+     * @param paths Paths of the files to remove (e.g., ["/file.txt"]).
      */
     withoutFiles: (paths: string[]) => Directory;
     /**
@@ -3144,6 +3161,7 @@ export declare class Host extends BaseClient {
      * The file is limited to a size of 512000 bytes.
      * @param name The user defined name for this secret.
      * @param path Location of the file to set as a secret.
+     * @deprecated setSecretFile is superceded by use of the secret API with file:// URIs
      */
     setSecretFile: (name: string, path: string) => Secret;
     /**
@@ -3313,10 +3331,6 @@ export declare class LLM extends BaseClient {
      * @param file The file to read the prompt from
      */
     withPromptFile: (file: File) => LLM;
-    /**
-     * Provide the entire Query object to the LLM
-     */
-    withQuery: () => LLM;
     /**
      * Add a system prompt to the LLM's environment
      * @param prompt The system prompt to send
@@ -3798,10 +3812,10 @@ export declare class Client extends BaseClient {
      */
     cacheVolume: (key: string, opts?: ClientCacheVolumeOpts) => CacheVolume;
     /**
-     * Creates a scratch container.
+     * Creates a scratch container, with no image or metadata.
      *
-     * Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.
-     * @param opts.platform Platform to initialize the container with.
+     * To pull an image, follow up with the "from" function.
+     * @param opts.platform Platform to initialize the container with. Defaults to the native platform of the current engine
      */
     container: (opts?: ClientContainerOpts) => Container;
     /**
@@ -3832,8 +3846,9 @@ export declare class Client extends BaseClient {
     engine: () => Engine;
     /**
      * Initialize a new environment
+     * @param opts.privileged Give the environment the same privileges as the caller: core API including host access, current module, and dependencies
      */
-    env: () => Env;
+    env: (opts?: ClientEnvOpts) => Env;
     /**
      * Create a new error.
      * @param message A brief description of the error.
@@ -4034,10 +4049,6 @@ export declare class Client extends BaseClient {
      * Load a Secret from its ID.
      */
     loadSecretFromID: (id: SecretID) => Secret;
-    /**
-     * Load a Secret from its Name.
-     */
-    loadSecretFromName: (name: string, opts?: ClientLoadSecretFromNameOpts) => Secret;
     /**
      * Load a Service from its ID.
      */