@dagger.io/dagger 0.3.4 → 0.3.5

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

@@ -33,7 +33,13 @@ declare class BaseClient {
     get queryTree(): QueryTree[];
 }
 export type BuildArg = {
+    /**
+     * The build argument name.
+     */
     name: string;
+    /**
+     * The build argument value.
+     */
     value: string;
 };
 /**
@@ -63,7 +69,8 @@ export declare enum CacheSharingMode {
 export type ContainerBuildOpts = {
     /**
      * Path to the Dockerfile to use.
-     * Defaults to './Dockerfile'.
+     *
+     * Default: './Dockerfile'.
      */
     dockerfile?: string;
     /**
@@ -75,21 +82,31 @@ export type ContainerBuildOpts = {
      */
     target?: string;
 };
+export type ContainerEndpointOpts = {
+    /**
+     * The exposed port number for the endpoint
+     */
+    port?: number;
+    /**
+     * Return a URL with the given scheme, eg. http for http://
+     */
+    scheme?: string;
+};
 export type ContainerExecOpts = {
     /**
-     * Command to run instead of the container's default command.
+     * Command to run instead of the container's default command (e.g., ["run", "main.go"]).
      */
     args?: string[];
     /**
-     * Content to write to the command's standard input before closing.
+     * Content to write to the command's standard input before closing (e.g., "Hello world").
      */
     stdin?: string;
     /**
-     * Redirect the command's standard output to a file in the container.
+     * Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
      */
     redirectStdout?: string;
     /**
-     * Redirect the command's standard error to a file in the container.
+     * Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
      */
     redirectStderr?: string;
     /**
@@ -117,38 +134,63 @@ export type ContainerPublishOpts = {
     platformVariants?: Container[];
 };
 export type ContainerWithDefaultArgsOpts = {
+    /**
+     * Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).
+     */
     args?: string[];
 };
 export type ContainerWithDirectoryOpts = {
+    /**
+     * Patterns to exclude in the written directory (e.g., ["node_modules/**", ".gitignore", ".git/"]).
+     */
     exclude?: string[];
+    /**
+     * Patterns to include in the written directory (e.g., ["*.go", "go.mod", "go.sum"]).
+     */
     include?: string[];
 };
 export type ContainerWithExecOpts = {
     /**
-     * Content to write to the command's standard input before closing.
+     * Content to write to the command's standard input before closing (e.g., "Hello world").
      */
     stdin?: string;
     /**
-     * Redirect the command's standard output to a file in the container.
+     * Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
      */
     redirectStdout?: string;
     /**
-     * Redirect the command's standard error to a file in the container.
+     * Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
      */
     redirectStderr?: string;
     /**
-     * Provide dagger access to the executed command.
+     * 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;
 };
+export type ContainerWithExposedPortOpts = {
+    /**
+     * Transport layer network protocol
+     */
+    protocol?: NetworkProtocol;
+    /**
+     * Optional port description
+     */
+    description?: string;
+};
 export type ContainerWithFileOpts = {
+    /**
+     * Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
+     */
     permissions?: number;
 };
 export type ContainerWithMountedCacheOpts = {
     /**
-     * Directory to use as the cache volume's root.
+     * Identifier of the directory to use as the cache volume's root.
      */
     source?: Directory;
     /**
@@ -157,9 +199,23 @@ export type ContainerWithMountedCacheOpts = {
     sharing?: CacheSharingMode;
 };
 export type ContainerWithNewFileOpts = {
+    /**
+     * Content of the file to write (e.g., "Hello world!").
+     */
     contents?: string;
+    /**
+     * Permission given to the written file (e.g., 0600).
+     *
+     * Default: 0644.
+     */
     permissions?: number;
 };
+export type ContainerWithoutExposedPortOpts = {
+    /**
+     * Port protocol to unexpose
+     */
+    protocol?: NetworkProtocol;
+};
 /**
  * A unique container identifier. Null designates an empty container (scratch).
  */
@@ -174,8 +230,9 @@ export type DateTime = string & {
 };
 export type DirectoryDockerBuildOpts = {
     /**
-     * Path to the Dockerfile to use.
-     * Defaults to './Dockerfile'.
+     * Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
+     *
+     * Defaults: './Dockerfile'.
      */
     dockerfile?: string;
     /**
@@ -183,7 +240,7 @@ export type DirectoryDockerBuildOpts = {
      */
     platform?: Platform;
     /**
-     * Additional build arguments.
+     * Build arguments to use in the build.
      */
     buildArgs?: BuildArg[];
     /**
@@ -192,6 +249,9 @@ export type DirectoryDockerBuildOpts = {
     target?: string;
 };
 export type DirectoryEntriesOpts = {
+    /**
+     * Location of the directory to look at (e.g., "/src").
+     */
     path?: string;
 };
 export type DirectoryPipelineOpts = {
@@ -199,23 +259,36 @@ export type DirectoryPipelineOpts = {
 };
 export type DirectoryWithDirectoryOpts = {
     /**
-     * Exclude artifacts that match the given pattern.
-     * (e.g. ["node_modules/", ".git*"]).
+     * Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
      */
     exclude?: string[];
     /**
-     * Include only artifacts that match the given pattern.
-     * (e.g. ["app/", "package.*"]).
+     * Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
      */
     include?: string[];
 };
 export type DirectoryWithFileOpts = {
+    /**
+     * Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
+     */
     permissions?: number;
 };
 export type DirectoryWithNewDirectoryOpts = {
+    /**
+     * Permission granted to the created directory (e.g., 0777).
+     *
+     * Default: 0755.
+     */
     permissions?: number;
 };
 export type DirectoryWithNewFileOpts = {
+    /**
+     * Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
+     */
     permissions?: number;
 };
 /**
@@ -235,11 +308,23 @@ export type GitRefTreeOpts = {
     sshAuthSocket?: Socket;
 };
 export type HostDirectoryOpts = {
+    /**
+     * Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
+     */
     exclude?: string[];
+    /**
+     * Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
+     */
     include?: string[];
 };
 export type HostWorkdirOpts = {
+    /**
+     * Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
+     */
     exclude?: string[];
+    /**
+     * Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
+     */
     include?: string[];
 };
 /**
@@ -248,9 +333,23 @@ export type HostWorkdirOpts = {
 export type ID = string & {
     __ID: never;
 };
+/**
+ * Transport layer network protocol associated to a port.
+ */
+export declare enum NetworkProtocol {
+    /**
+     * TCP (Transmission Control Protocol)
+     */
+    Tcp = 0,
+    /**
+     * UDP (User Datagram Protocol)
+     */
+    Udp = 1
+}
 /**
  * The platform config OS and architecture in a Container.
- * The format is [os]/[platform]/[version] (e.g. darwin/arm64/v7, windows/amd64, linux/arm64).
+ *
+ * The format is [os]/[platform]/[version] (e.g., "darwin/arm64/v7", "windows/amd64", "linux/arm64").
  */
 export type Platform = string & {
     __Platform: never;
@@ -263,7 +362,20 @@ export type ClientDirectoryOpts = {
     id?: DirectoryID;
 };
 export type ClientGitOpts = {
+    /**
+     * Set to true to keep .git directory.
+     */
     keepGitDir?: boolean;
+    /**
+     * A service which must be started before the repo is fetched.
+     */
+    experimentalServiceHost?: Container;
+};
+export type ClientHttpOpts = {
+    /**
+     * A service which must be started before the URL is fetched.
+     */
+    experimentalServiceHost?: Container;
 };
 export type ClientPipelineOpts = {
     description?: string;
@@ -322,10 +434,11 @@ export declare class CacheVolume extends BaseClient {
  */
 export declare class Container extends BaseClient {
     /**
-     * Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs.
+     * Initializes this container from a Dockerfile build.
      * @param context Directory context used by the Dockerfile.
      * @param opts.dockerfile Path to the Dockerfile to use.
-  Defaults to './Dockerfile'.
+     *
+     * Default: './Dockerfile'.
      * @param opts.buildArgs Additional build arguments.
      * @param opts.target Target build stage to build.
      */
@@ -335,15 +448,29 @@ export declare class Container extends BaseClient {
      */
     defaultArgs(): Promise<string[]>;
     /**
-     * Retrieves a directory at the given path. Mounts are included.
+     * Retrieves a directory at the given path.
+     *
+     * Mounts are included.
+     * @param path The path of the directory to retrieve (e.g., "./src").
      */
     directory(path: string): Directory;
+    /**
+     * Retrieves an endpoint that clients can use to reach this container.
+     *
+     * If no port is specified, the first exposed port is used. If none exist an error is returned.
+     *
+     * If a scheme is specified, a URL is returned. Otherwise, a host:port pair is returned.
+     * @param opts.port The exposed port number for the endpoint
+     * @param opts.scheme Return a URL with the given scheme, eg. http for http://
+     */
+    endpoint(opts?: ContainerEndpointOpts): Promise<string>;
     /**
      * Retrieves entrypoint to be prepended to the arguments of all commands.
      */
     entrypoint(): Promise<string[]>;
     /**
      * Retrieves the value of the specified environment variable.
+     * @param name The name of the environment variable to retrieve (e.g., "PATH").
      */
     envVariable(name: string): Promise<string>;
     /**
@@ -352,13 +479,13 @@ export declare class Container extends BaseClient {
     envVariables(): Promise<EnvVariable[]>;
     /**
      * Retrieves this container after executing the specified command inside it.
-     * @param opts.args Command to run instead of the container's default command.
-     * @param opts.stdin Content to write to the command's standard input before closing.
-     * @param opts.redirectStdout Redirect the command's standard output to a file in the container.
-     * @param opts.redirectStderr Redirect the command's standard error to a file in the container.
+     * @param opts.args Command to run instead of the container's default command (e.g., ["run", "main.go"]).
+     * @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").
      * @param opts.experimentalPrivilegedNesting Provide 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.
+     * 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.
      * @deprecated Replaced by withExec.
      */
     exec(opts?: ContainerExecOpts): Container;
@@ -368,22 +495,32 @@ export declare class Container extends BaseClient {
      */
     exitCode(): Promise<number>;
     /**
-     * Writes the container as an OCI tarball to the destination file path on the host for the specified platformVariants.
+     * Writes the container as an OCI tarball to the destination file path on the host for the specified platform variants.
+     *
      * Return true on success.
-     * @param path Host's destination path.
-  Path can be relative to the engine's workdir or absolute.
+     * It can also publishes platform variants.
+     * @param path Host's destination path (e.g., "./tarball").
+     * Path can be relative to the engine's workdir or absolute.
      * @param opts.platformVariants Identifiers for other platform specific containers.
-  Used for multi-platform image.
+     * Used for multi-platform image.
      */
     export(path: string, opts?: ContainerExportOpts): Promise<boolean>;
     /**
-     * Retrieves a file at the given path. Mounts are included.
+     * Retrieves the list of exposed ports
+     */
+    exposedPorts(): Promise<Port[]>;
+    /**
+     * Retrieves a file at the given path.
+     *
+     * Mounts are included.
+     * @param path The path of the file to retrieve (e.g., "./README.md").
      */
     file(path: string): File;
     /**
-     * Initializes this container from the base image published at the given address.
+     * 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).
+     *
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").
      */
     from(address: string): Container;
     /**
@@ -391,10 +528,18 @@ export declare class Container extends BaseClient {
      * @deprecated Replaced by rootfs.
      */
     fs(): Directory;
+    /**
+     * Retrieves a hostname which can be used by clients to reach this container.
+     */
+    hostname(): Promise<string>;
     /**
      * A unique identifier for this container.
      */
     id(): Promise<ContainerID>;
+    /**
+     * The unique image reference which can only be retrieved immediately after the 'Container.From' call.
+     */
+    imageRef(): Promise<string>;
     /**
      * Retrieves the value of the specified label.
      */
@@ -416,11 +561,15 @@ export declare class Container extends BaseClient {
      */
     platform(): Promise<Platform>;
     /**
-     * Publishes this container as a new image to the specified address, for the platformVariants, returning a fully qualified ref.
+     * Publishes this container as a new image to the specified address.
+     *
+     * Publish returns a fully qualified ref.
+     * 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).
+     *
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g. "docker.io/dagger/dagger:main").
      * @param opts.platformVariants Identifiers for other platform specific containers.
-  Used for multi-platform image.
+     * Used for multi-platform image.
      */
     publish(address: string, opts?: ContainerPublishOpts): Promise<string>;
     /**
@@ -443,31 +592,50 @@ export declare class Container extends BaseClient {
     user(): Promise<string>;
     /**
      * Configures default arguments for future commands.
+     * @param opts.args Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).
      */
     withDefaultArgs(opts?: ContainerWithDefaultArgsOpts): Container;
     /**
      * Retrieves this container plus a directory written at the given path.
+     * @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/"]).
+     * @param opts.include Patterns to include in the written directory (e.g., ["*.go", "go.mod", "go.sum"]).
      */
     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"]).
      */
     withEntrypoint(args: string[]): 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").
      */
     withEnvVariable(name: string, value: string): Container;
     /**
      * Retrieves this container after executing the specified command inside it.
-     * @param args Command to run instead of the container's default command.
-     * @param opts.stdin Content to write to the command's standard input before closing.
-     * @param opts.redirectStdout Redirect the command's standard output to a file in the container.
-     * @param opts.redirectStderr Redirect the command's standard error to a file in the container.
-     * @param opts.experimentalPrivilegedNesting Provide 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.
+     * @param args Command to run instead of the container's default command (e.g., ["run", "main.go"]).
+     * @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").
+     * @param opts.experimentalPrivilegedNesting 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.
      */
     withExec(args: string[], opts?: ContainerWithExecOpts): Container;
+    /**
+     * Expose a network port.
+     * 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
+     */
+    withExposedPort(port: number, opts?: ContainerWithExposedPortOpts): Container;
     /**
      * Initializes this container from this DirectoryID.
      * @deprecated Replaced by withRootfs.
@@ -475,44 +643,63 @@ export declare class Container extends BaseClient {
     withFS(id: Directory): 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).
+     *
+     * Default: 0644.
      */
     withFile(path: string, source: File, opts?: ContainerWithFileOpts): Container;
     /**
      * Retrieves this container plus the given label.
+     * @param name The name of the label (e.g., "org.opencontainers.artifact.created").
+     * @param value The value of the label (e.g., "2023-01-01T00:00:00Z").
      */
     withLabel(name: string, value: string): Container;
     /**
      * Retrieves this container plus a cache volume mounted at the given path.
-     * @param path Path to mount the cache volume at.
-     * @param cache ID of the cache to mount.
-     * @param opts.source Directory to use as the cache volume's root.
+     * @param path Location of the cache directory (e.g., "/cache/node_modules").
+     * @param cache Identifier of the cache volume to mount.
+     * @param opts.source Identifier of the directory to use as the cache volume's root.
      * @param opts.sharing Sharing mode of the cache volume.
      */
     withMountedCache(path: string, cache: CacheVolume, opts?: ContainerWithMountedCacheOpts): Container;
     /**
      * Retrieves this container plus a directory mounted at the given path.
+     * @param path Location of the mounted directory (e.g., "/mnt/directory").
+     * @param source Identifier of the mounted directory.
      */
     withMountedDirectory(path: string, source: Directory): Container;
     /**
      * Retrieves this container plus a file mounted at the given path.
+     * @param path Location of the mounted file (e.g., "/tmp/file.txt").
+     * @param source Identifier of the mounted file.
      */
     withMountedFile(path: string, source: File): Container;
     /**
      * Retrieves this container plus a secret mounted into a file at the given path.
+     * @param path Location of the secret file (e.g., "/tmp/secret.txt").
+     * @param source Identifier of the secret to mount.
      */
     withMountedSecret(path: string, source: Secret): Container;
     /**
      * Retrieves this container plus a temporary directory mounted at the given path.
+     * @param path Location of the temporary directory (e.g., "/tmp/temp_dir").
      */
     withMountedTemp(path: string): 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 opts.contents Content of the file to write (e.g., "Hello world!").
+     * @param opts.permissions Permission given to the written file (e.g., 0600).
+     *
+     * Default: 0644.
      */
     withNewFile(path: 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).
+     * 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.
      */
@@ -523,40 +710,66 @@ export declare class Container extends BaseClient {
     withRootfs(id: 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.
      */
     withSecretVariable(name: string, secret: Secret): Container;
+    /**
+     * Establish a runtime dependency on a service. The service will be started automatically when needed and detached when it is no longer needed.
+     *
+     * 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
+     */
+    withServiceBinding(alias: string, service: Container): Container;
     /**
      * Retrieves this container plus a socket forwarded to the given Unix socket path.
+     * @param path Location of the forwarded Unix socket (e.g., "/tmp/socket").
+     * @param source Identifier of the socket to forward.
      */
     withUnixSocket(path: string, source: Socket): Container;
     /**
-     * Retrieves this containers with a different command user.
+     * Retrieves this container with a different command user.
+     * @param name The user to set (e.g., "root").
      */
     withUser(name: string): Container;
     /**
      * Retrieves this container with a different working directory.
+     * @param path The path to set as the working directory (e.g., "/app").
      */
     withWorkdir(path: string): Container;
     /**
      * Retrieves this container minus the given environment variable.
+     * @param name The name of the environment variable (e.g., "HOST").
      */
     withoutEnvVariable(name: string): Container;
+    /**
+     * Unexpose a previously exposed port.
+     * @param port Port number to unexpose
+     * @param opts.protocol Port protocol to unexpose
+     */
+    withoutExposedPort(port: number, opts?: ContainerWithoutExposedPortOpts): Container;
     /**
      * Retrieves this container minus the given environment label.
+     * @param name The name of the label to remove (e.g., "org.opencontainers.artifact.created").
      */
     withoutLabel(name: string): Container;
     /**
      * Retrieves this container after unmounting everything at the given path.
+     * @param path Location of the cache directory (e.g., "/cache/node_modules").
      */
     withoutMount(path: string): Container;
     /**
      * Retrieves this container without the registry authentication of a given address.
      * @param address Registry's address to remove the authentication from.
-  Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
      */
     withoutRegistryAuth(address: string): Container;
     /**
      * Retrieves this container with a previously added Unix socket removed.
+     * @param path Location of the socket to remove (e.g., "/tmp/socket").
      */
     withoutUnixSocket(path: string): Container;
     /**
@@ -592,31 +805,37 @@ export declare class Container extends BaseClient {
 export declare class Directory extends BaseClient {
     /**
      * Gets the difference between this directory and an another directory.
+     * @param other Identifier of the directory to compare.
      */
     diff(other: Directory): Directory;
     /**
      * Retrieves a directory at the given path.
+     * @param path Location of the directory to retrieve (e.g., "/src").
      */
     directory(path: string): Directory;
     /**
      * Builds a new Docker container from this directory.
-     * @param opts.dockerfile Path to the Dockerfile to use.
-  Defaults to './Dockerfile'.
+     * @param opts.dockerfile Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
+     *
+     * Defaults: './Dockerfile'.
      * @param opts.platform The platform to build.
-     * @param opts.buildArgs Additional build arguments.
+     * @param opts.buildArgs Build arguments to use in the build.
      * @param opts.target Target build stage to build.
      */
     dockerBuild(opts?: DirectoryDockerBuildOpts): Container;
     /**
      * Returns a list of files and directories at the given path.
+     * @param opts.path Location of the directory to look at (e.g., "/src").
      */
     entries(opts?: DirectoryEntriesOpts): Promise<string[]>;
     /**
      * Writes the contents of the directory to a path on the host.
+     * @param path Location of the copied directory (e.g., "logs/").
      */
     export(path: string): Promise<boolean>;
     /**
      * Retrieves a file at the given path.
+     * @param path Location of the file to retrieve (e.g., "README.md").
      */
     file(path: string): File;
     /**
@@ -633,34 +852,53 @@ export declare class Directory extends BaseClient {
     pipeline(name: string, opts?: DirectoryPipelineOpts): Directory;
     /**
      * Retrieves this directory plus a directory written at the given path.
-     * @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.*"]).
+     * @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*"]).
+     * @param opts.include Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
      */
     withDirectory(path: string, directory: Directory, opts?: DirectoryWithDirectoryOpts): Directory;
     /**
      * Retrieves this directory plus the contents of the given file copied to the given path.
+     * @param path Location of the copied file (e.g., "/file.txt").
+     * @param source Identifier of the file to copy.
+     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
      */
     withFile(path: string, source: File, opts?: DirectoryWithFileOpts): Directory;
     /**
      * Retrieves this directory plus a new directory created at the given path.
+     * @param path Location of the directory created (e.g., "/logs").
+     * @param opts.permissions Permission granted to the created directory (e.g., 0777).
+     *
+     * Default: 0755.
      */
     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).
+     *
+     * Default: 0644.
      */
     withNewFile(path: string, contents: string, opts?: DirectoryWithNewFileOpts): Directory;
     /**
-     * Retrieves this directory with all file/dir timestamps set to the given time, in seconds from the Unix epoch.
+     * Retrieves this directory with all file/dir timestamps set to the given time.
+     * @param timestamp Timestamp to set dir/files in.
+     *
+     * Formatted in seconds following Unix epoch (e.g., 1672531199).
      */
     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/").
      */
     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").
      */
     withoutFile(path: string): Directory;
     /**
@@ -731,6 +969,7 @@ export declare class File extends BaseClient {
     contents(): Promise<string>;
     /**
      * Writes the file to a file path on the host.
+     * @param path Location of the written directory (e.g., "output.txt").
      */
     export(path: string): Promise<boolean>;
     /**
@@ -746,7 +985,10 @@ export declare class File extends BaseClient {
      */
     size(): Promise<number>;
     /**
-     * Retrieves this file with its created/modified timestamps set to the given time, in seconds from the Unix epoch.
+     * Retrieves this file with its created/modified timestamps set to the given time.
+     * @param timestamp Timestamp to set dir/files in.
+     *
+     * Formatted in seconds following Unix epoch (e.g., 1672531199).
      */
     withTimestamps(timestamp: number): File;
     /**
@@ -813,6 +1055,7 @@ export declare class GitRef extends BaseClient {
 export declare class GitRepository extends BaseClient {
     /**
      * Returns details on one branch.
+     * @param name Branch's name (e.g., "main").
      */
     branch(name: string): GitRef;
     /**
@@ -821,10 +1064,12 @@ export declare class GitRepository extends BaseClient {
     branches(): Promise<string[]>;
     /**
      * Returns details on one commit.
+     * @param id Identifier of the commit (e.g., "b6315d8f2810962c601af73f86831f6866ea798b").
      */
     commit(id: string): GitRef;
     /**
      * Returns details on one tag.
+     * @param name Tag's name (e.g., "v0.3.9").
      */
     tag(name: string): GitRef;
     /**
@@ -860,18 +1105,25 @@ export declare class GitRepository extends BaseClient {
 export declare class Host extends BaseClient {
     /**
      * Accesses a directory on the host.
+     * @param path Location of the directory to access (e.g., ".").
+     * @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.*"]).
      */
     directory(path: string, opts?: HostDirectoryOpts): Directory;
     /**
      * Accesses an environment variable on the host.
+     * @param name Name of the environment variable (e.g., "PATH").
      */
     envVariable(name: string): HostVariable;
     /**
      * Accesses a Unix socket on the host.
+     * @param path Location of the Unix socket (e.g., "/var/run/docker.sock").
      */
     unixSocket(path: string): Socket;
     /**
      * Retrieves the current working directory on the host.
+     * @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.*"]).
      * @deprecated Use directory with path set to '.' instead.
      */
     workdir(opts?: HostWorkdirOpts): Directory;
@@ -968,6 +1220,45 @@ export declare class Label extends BaseClient {
      */
     with(arg: (param: Label) => Label): Label;
 }
+/**
+ * A port exposed by a container.
+ */
+export declare class Port extends BaseClient {
+    /**
+     * The port description.
+     */
+    description(): Promise<string>;
+    /**
+     * The port number.
+     */
+    port(): Promise<number>;
+    /**
+     * The transport layer network protocol.
+     */
+    protocol(): Promise<NetworkProtocol>;
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg: (param: Port) => Port): Port;
+}
 /**
  * A set of scripts and/or extensions
  */
@@ -1022,13 +1313,15 @@ export declare class Project extends BaseClient {
 export default class Client extends BaseClient {
     /**
      * Constructs a cache volume for a given cache key.
-     * @param key A string identifier to target this cache volume (e.g. "myapp-cache").
+     * @param key A string identifier to target this cache volume (e.g., "modules-cache").
      */
     cacheVolume(key: string): CacheVolume;
     /**
      * Loads a container from ID.
+     *
      * Null ID returns an empty container (scratch).
-     * Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.
+     * Optional platform argument initializes new containers to execute and publish as that platform.
+     * Platform defaults to that of the builder's host.
      */
     container(opts?: ClientContainerOpts): Container;
     /**
@@ -1045,6 +1338,11 @@ export default class Client extends BaseClient {
     file(id: FileID): File;
     /**
      * Queries a git repository.
+     * @param url Url of the git repository.
+     * Can be formatted as https://{host}/{owner}/{repo}, git@{host}/{owner}/{repo}
+     * Suffix ".git" is optional.
+     * @param opts.keepGitDir Set to true to keep .git directory.
+     * @param opts.experimentalServiceHost A service which must be started before the repo is fetched.
      */
     git(url: string, opts?: ClientGitOpts): GitRepository;
     /**
@@ -1053,8 +1351,10 @@ export default class Client extends BaseClient {
     host(): Host;
     /**
      * Returns a file containing an http remote url content.
+     * @param url HTTP url to get the content from (e.g., "https://docs.dagger.io").
+     * @param opts.experimentalServiceHost A service which must be started before the URL is fetched.
      */
-    http(url: string): File;
+    http(url: string, opts?: ClientHttpOpts): File;
     /**
      * Creates a named sub-pipeline
      */