# CommandSection

title: PARAMETERS
content:
<b>-a, --author string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the author for the committed image (e.g., 'John Doe <john.doe@example.com>').<br><br><b>-c, --change list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply Dockerfile instructions to the new image (e.g., <b>CMD ["new-command"]</b>, <b>EXPOSE 8080</b>, <b>ENV VAR=value</b>).<br><br><b>-m, --message string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a commit message for the new image, similar to a Git commit message.<br><br><b>-p, --pause</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pause the container during the commit process (default is <b>true</b>). Pausing ensures data consistency.<br><br><b>-s, --squash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Squash all new layers into a single new layer (experimental feature).<br><br>


title: DESCRIPTION
content:
The <b>docker commit</b> command creates a new Docker image from the changes made to an existing container. It essentially captures the current state of a running or stopped container, including any modifications to its filesystem, configuration, or installed software, and saves it as a new image layer. This command is often used for debugging, quickly saving a working state, or for creating a base image from a manually configured container. However, for reproducible and robust image building, the use of a <i>Dockerfile</i> with <b>docker build</b> is highly recommended. The <b>docker commit</b> operation adds a new layer on top of the container's base image, preserving the history of changes made within the container. It's a quick way to package changes, but lacks the transparency and automation of a proper build process.


title: CAVEATS
content:
While <b>docker commit</b> is useful for quick snapshots or debugging, it is <i>not recommended</i> for building production-ready images due to its lack of reproducibility. Changes made with <b>docker commit</b> are opaque and cannot be easily tracked, versioned, or audited, unlike changes defined in a <i>Dockerfile</i>. Prefer using <b>docker build</b> with a <i>Dockerfile</i> for any image intended for deployment, collaboration, or long-term maintenance.


title: IMAGE LAYERS AND REPRODUCIBILITY
content:
When you commit a container, Docker creates a new read-only layer containing all the changes made to the container's filesystem. This new layer is then added on top of the original image layers. While this process is efficient in terms of storage and quick for snapshots, it creates a non-reproducible artifact. The exact steps leading to the committed image are not recorded within the image itself, making it difficult to rebuild the image identically or to understand the provenance of its contents. This lack of transparency and reproducibility is a primary reason why <i>Dockerfile</i>s are universally favored for serious image building.


title: HISTORY
content:
The <b>docker commit</b> command has been a core part of Docker since its early days, serving as one of the initial methods for creating new images. Its primary role in image creation diminished significantly with the widespread adoption and maturation of <i>Dockerfile</i>s, which offer a more declarative, reproducible, and transparent way to define image builds. Today, it is more commonly used for ad-hoc image capturing, debugging, or personal experimentation rather than for formal, automated image build pipelines.


title: PARAMETERS
content:
<b><b>-f, --file FILE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternate Compose file (default: <i>docker-compose.yml</i>).<br><br><b><b>-p, --project-name NAME</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternate project name (default: directory name).<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more output.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show version information and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message and exit.<br><br><b><b>up [OPTIONS] [SERVICE...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create and start containers. Commonly used options include <b>-d</b> (detached mode) and <b>--build</b> (build images before starting).<br><br><b><b>down [OPTIONS]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop and remove containers, networks, images, and volumes created by <b>up</b>. Options like <b>--volumes</b> can remove named volumes.<br><br><b><b>build [OPTIONS] [SERVICE...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Build or rebuild images for services. Option <b>--no-cache</b> can be used to disable cache during build.<br><br><b><b>ps [OPTIONS]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List containers for the current project. Use <b>-a</b> to show all (stopped, running, etc.) containers.<br><br><b><b>logs [OPTIONS] [SERVICE...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;View output from services' containers. Options like <b>-f</b> (follow) and <b>--tail N</b> (show last N lines) are common.<br><br><b><b>exec [OPTIONS] SERVICE COMMAND [ARGS...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute a command in a running container. Often used with <b>-it</b> for interactive sessions.<br><br><b><b>run [OPTIONS] SERVICE [COMMAND] [ARGS...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run a one-off command on a service. Similar to <b>exec</b> but creates a new container; <b>--rm</b> removes it on exit.<br><br><b><b>start [SERVICE...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start existing stopped services.<br><br><b><b>stop [SERVICE...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop running services without removing them.<br><br><b><b>restart [SERVICE...]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restart services.<br><br><b><b>config [OPTIONS]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Validate and view the Compose file configuration.<br><br>


title: DESCRIPTION
content:
<i>docker-compose</i> is a powerful tool designed to simplify the definition and management of multi-container Docker applications. It leverages a YAML file, typically named <i>docker-compose.yml</i>, to configure an application's services, networks, and volumes. With a single command, developers can build, start, stop, and manage all the services specified in the configuration.<br><br>This utility streamlines the development, testing, and staging workflows by allowing an entire application stack to be treated as a single unit. It orchestrates the lifecycle of multiple containers, including building images, creating custom networks, attaching volumes, and ensuring services start in the correct order. <i>docker-compose</i> is particularly beneficial for complex applications comprising several interdependent microservices, such as a web application with separate database, caching, and message queue components.<br><br>It promotes consistency across different environments (development, CI, production) since the same <i>docker-compose.yml</i> file can be used. Although primarily focused on development and testing environments, its ease of use and declarative configuration make it an indispensable tool for many Docker users.


title: CAVEATS
content:
<i>docker-compose</i> is primarily intended for local development and testing environments, or for CI/CD pipelines. It is <b>not</b> designed as a production-grade orchestrator for large-scale, highly available, or distributed applications. For such scenarios, solutions like Kubernetes or Docker Swarm are more appropriate.<br><br>Managing sensitive information (e.g., API keys, database credentials) directly in the <i>docker-compose.yml</i> file is not recommended; consider using environment variables or Docker secrets for better security practices.


title: COMPOSE FILE FORMAT
content:
The heart of <i>docker-compose</i> is the <i>docker-compose.yml</i> file. This YAML file defines services, networks, and volumes for your application. It supports different versions, with <i>'3.x'</i> being the latest recommended version, offering features like defining build contexts, environment variables, dependencies, and health checks for services.


title: DOCKER-COMPOSE VS. DOCKER COMPOSE
content:
It's crucial to distinguish between <i><b>docker-compose</b></i> (the standalone Python-based CLI) and <i><b>docker compose</b></i> (the Go-based plugin integrated into the main Docker CLI). While they serve the same purpose and largely use the same Compose file format, <i>docker compose</i> is the newer, actively maintained, and recommended version for modern Docker installations. The original <i>docker-compose</i> might be deprecated in future Docker versions, but it is still widely used in existing projects.


title: HISTORY
content:
<i>docker-compose</i> originated from a project called <i>Fig</i>, which was acquired by Docker Inc. in 2014 and subsequently rebranded. It was initially implemented in Python and provided a convenient way to define and run multi-container applications using a YAML configuration. Its development focused on simplifying the setup of development environments and streamlining CI/CD workflows.<br><br>More recently, Docker introduced a new, Go-based implementation of Compose, integrated directly into the Docker CLI as a plugin (invoked as <i>docker compose</i>, without the hyphen). While the original <i>docker-compose</i> (hyphenated) command still functions, the unhyphenated version is the recommended and actively developed successor.


title: SYNOPSIS
content:
<I>docker container</I> [<B>OPTIONS</B>] <B>COMMAND</B> [<B>ARG...</B>]<br><br>Common <B>COMMAND</B>s include:<br>&nbsp;&nbsp;<I>attach</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Attach local standard input, output, and error streams to a running container<br>&nbsp;&nbsp;<I>commit</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create a new image from a container's changes<br>&nbsp;&nbsp;<I>cp</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Copy files/folders between a container and the local filesystem<br>&nbsp;&nbsp;<I>create</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create a new container<br>&nbsp;&nbsp;<I>diff</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Inspect changes on files or directories in a container's filesystem<br>&nbsp;&nbsp;<I>exec</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Run a command in a running container<br>&nbsp;&nbsp;<I>inspect</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information on one or more containers<br>&nbsp;&nbsp;<I>kill</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Kill one or more running containers<br>&nbsp;&nbsp;<I>logs</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fetch the logs of a container<br>&nbsp;&nbsp;<I>ls</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List containers<br>&nbsp;&nbsp;<I>pause</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Pause all processes within one or more containers<br>&nbsp;&nbsp;<I>port</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List port mappings or a specific mapping for the container<br>&nbsp;&nbsp;<I>prune</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Remove all stopped containers<br>&nbsp;&nbsp;<I>rename</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Rename a container<br>&nbsp;&nbsp;<I>restart</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Restart one or more containers<br>&nbsp;&nbsp;<I>rm</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Remove one or more containers<br>&nbsp;&nbsp;<I>run</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Run a command in a new container<br>&nbsp;&nbsp;<I>start</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Start one or more stopped containers<br>&nbsp;&nbsp;<I>stats</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Display a live stream of container(s) resource usage statistics<br>&nbsp;&nbsp;<I>stop</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Stop one or more running containers<br>&nbsp;&nbsp;<I>top</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Display the running processes of a container<br>&nbsp;&nbsp;<I>unpause</I>&nbsp;&nbsp;&nbsp;&nbsp;Unpause all processes within one or more containers<br>&nbsp;&nbsp;<I>update</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Update configuration of one or more containers<br>&nbsp;&nbsp;<I>wait</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block until one or more containers stop, then print their exit codes


title: PARAMETERS
content:
<b>attach <CONTAINER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach to a running container's standard input, output, and error streams.<br><br><b>commit <CONTAINER> [REPOSITORY[:TAG]]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new image from a container's changes.<br><br><b>cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|- OR SRC_PATH CONTAINER:DEST_PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copy files/folders between a container and the local filesystem.<br><br><b>create [OPTIONS] IMAGE [COMMAND] [ARG...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new container, but do not start it immediately.<br><br><b>diff <CONTAINER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inspect changes on files or directories in a container's filesystem.<br><br><b>exec [OPTIONS] <CONTAINER> <COMMAND> [ARG...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run a command in a running container.<br><br><b>inspect [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information on one or more containers.<br><br><b>kill [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Kill one or more running containers (sends SIGKILL by default).<br><br><b>logs [OPTIONS] <CONTAINER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fetch the logs of a container.<br><br><b>ls [OPTIONS]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List containers. This is an alias for <I>docker ps</I>.<br><br><b>pause <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pause all processes within one or more running containers.<br><br><b>port <CONTAINER> [PRIVATE_PORT[/PROTOCOL]]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List port mappings or a specific mapping for the container.<br><br><b>prune [OPTIONS]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all stopped containers.<br><br><b>rename <OLD_NAME> <NEW_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rename an existing container.<br><br><b>restart [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restart one or more containers.<br><br><b>rm [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove one or more containers.<br><br><b>run [OPTIONS] <IMAGE> [COMMAND] [ARG...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run a command in a new container.<br><br><b>start [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start one or more stopped containers.<br><br><b>stats [OPTIONS] [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a live stream of container(s) resource usage statistics.<br><br><b>stop [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop one or more running containers.<br><br><b>top <CONTAINER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the running processes of a container.<br><br><b>unpause <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unpause all processes within one or more containers.<br><br><b>update [OPTIONS] <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update configuration of one or more containers.<br><br><b>wait <CONTAINER> [CONTAINER...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Block until one or more containers stop, then print their exit codes.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print usage statement for <I>docker container</I> or its specific subcommands.<br><br>


title: DESCRIPTION
content:
The "docker-container" (more accurately, <I>docker container</I>) command group is a fundamental component of the Docker command-line interface (CLI) used for managing Docker containers. It provides a comprehensive set of tools to control the lifecycle of containers, from creation and execution to stopping, restarting, and removal. This subcommand consolidates operations that were previously available directly under the main <I>docker</I> command (e.g., <I>docker ps</I> became <I>docker container ls</I>). By organizing container-related functionalities into a dedicated group, Docker improved the CLI's discoverability and consistency. Users leverage <I>docker container</I> to interact with the Docker daemon, enabling them to inspect running containers, view logs, copy files, execute commands inside containers, and perform various maintenance tasks.


title: CAVEATS
content:
The <I>docker container</I> command group is a subcommand of the main <I>docker</I> CLI, not a standalone executable. It requires the Docker daemon to be running on the host system. Users typically need appropriate permissions (e.g., being part of the <I>docker</I> Unix group or running with <I>sudo</I>) to interact with the Docker daemon. The exact behavior and available options for each subcommand can vary slightly between Docker Engine versions. While older top-level commands like <I>docker ps</I> or <I>docker run</I> often still work for backward compatibility, using the namespaced <I>docker container</I> equivalents is the recommended modern approach.


title: COMMON WORKFLOWS
content:
Typical workflows involving the <I>docker container</I> command include:<br>1.  <I>Pull an image:</I> <B>docker pull &lt;image_name&gt;</B><br>2.  <I>Run a new container:</I> <B>docker container run -d -p 80:80 --name mynginx nginx</B><br>3.  <I>List running containers:</I> <B>docker container ls</B><br>4.  <I>Execute a command inside a running container:</I> <B>docker container exec -it mynginx bash</B><br>5.  <I>Inspect a container:</I> <B>docker container inspect mynginx</B><br>6.  <I>Stop a container:</I> <B>docker container stop mynginx</B><br>7.  <I>Remove a stopped container:</I> <B>docker container rm mynginx</B><br>8.  <I>Clean up all stopped containers:</I> <B>docker container prune</B>


title: CONTAINER STATES
content:
Docker containers can exist in several states, which are reflected by the <I>docker container ls</I> (or <I>docker ps</I>) command:<br><ul><li><I>Created</I>: The container has been created but not started.</li><li><I>Running</I>: The container is actively executing its primary process.</li><li><I>Paused</I>: The container's processes have been suspended.</li><li><I>Restarting</I>: The container is in the process of restarting.</li><li><I>Exited</I>: The container's primary process has finished or been terminated.</li><li><I>Dead</I>: The container should not be running and Docker has attempted to stop it.</li></ul>


title: HISTORY
content:
Before Docker Engine version 1.13 (released in January 2017), many common Docker commands like <I>docker ps</I>, <I>docker run</I>, and <I>docker stop</I> were top-level commands directly under the <I>docker</I> CLI. As Docker's functionality expanded and its command-line interface grew, it became increasingly complex. To address this, Docker introduced a modular subcommand structure. Commands were logically grouped into namespaces such as <I>docker container</I>, <I>docker image</I>, <I>docker network</I>, and <I>docker volume</I>. This change aimed to improve discoverability, organization, and consistency of the CLI, making it easier for users to find and use related commands. While the old top-level commands are often aliased or still functional for backward compatibility, the <I>docker container</I> group represents the modern, preferred way to manage containers.


title: PARAMETERS
content:
<b>CONTAINER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name or ID of the Docker container to inspect for filesystem differences.<br><br>


title: DESCRIPTION
content:
The command 'docker-container-diff' is not a standard, built-in command of the Docker CLI. However, the functionality it implies—inspecting differences in a Docker container's filesystem—is primarily provided by the built-in <I>docker diff</I> command. This command allows users to view changes made to a running or stopped container's filesystem relative to its original image. It provides a simple output format indicating added, deleted, or modified files and directories. For more advanced comparisons, particularly between container <I>images</I> or for detailed analysis of layers and contents (like packages), external tools such as 'container-diff' (developed by Google) are often used. This entry describes the capabilities typically associated with 'docker-container-diff' through the lens of the <I>docker diff</I> command.


title: CAVEATS
content:
The command 'docker-container-diff' is not a standard Docker CLI command. The functionality described here pertains to the built-in <I>docker diff</I> command.<br><br>The <I>docker diff</I> command only shows differences in the <I>filesystem</I> of a container relative to its base image. It does not provide insights into other changes such as process status, network configuration, environment variables, or resource usage. It also doesn't compare the state of a container to another container or a local directory directly.


title: OUTPUT FORMAT
content:
The output of <I>docker diff</I> uses single-character prefixes to indicate the type of change:<br><b>A</b>: A file or directory has been Added.<br><b>D</b>: A file or directory has been Deleted.<br><b>C</b>: A file or directory has been Changed (modified content or metadata).


title: COMPARING CONTAINER IMAGES
content:
While <I>docker diff</I> focuses on a running container's filesystem, comparing two Docker <I>images</I> (e.g., to see changes between versions) requires different tools. Tools like 'container-diff' (by Google) offer more comprehensive capabilities for comparing image layers, installed packages, or specific file contents across different image versions or sources.


title: HISTORY
content:
The <I>docker diff</I> command has been a fundamental part of the Docker CLI since its early versions. It provides a straightforward way for developers and system administrators to quickly ascertain what changes have occurred within a container's writable layer during its lifecycle. Its simplicity and direct utility have made it a persistent and useful tool in Docker's suite of commands, often used for debugging, security auditing, or understanding application behavior inside containers.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the removal of a running container (sends a SIGKILL signal).<br><br><b><b>-l</b>, <b>--link</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the specified link (legacy feature for container linking).<br><br><b><b>-v</b>, <b>--volumes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove anonymous volumes associated with the container. Named volumes are not removed by default.<br><br>


title: DESCRIPTION
content:
<b>docker rm</b> is a fundamental command for managing the Docker environment. It is used to <I>remove one or more stopped Docker containers</I> from the host system. This action is crucial for reclaiming disk space and maintaining a clean Docker setup, especially in development or testing environments where containers are frequently created and discarded.<br><br>By default, <b>docker rm</b> can only remove containers that are not running. If a container is active, it must first be stopped using <b>docker stop</b> or <b>docker kill</b>, or alternatively, the <b>-f</b> or <b>--force</b> option can be used to forcefully remove a running container, which sends a SIGKILL signal. When a container is removed, its writable layer is deleted, but the base image it was built from remains available on the system. It's important to note that <b>docker rm</b> does not automatically remove volumes or networks associated with the container unless specified with the <b>-v</b> option for anonymous volumes.


title: CAVEATS
content:
<I>Running Containers:</I> Cannot remove a running container without the <b>-f</b> or <b>--force</b> option. Forcing removal can lead to data loss if the application within the container hasn't shut down gracefully.<br><br><I>Named Volumes:</I> The <b>-v</b> option only removes <I>anonymous</I> volumes. Named volumes, which persist data even after the container is removed, must be explicitly removed using <b>docker volume rm</b>.<br><br><I>Images:</I> <b>docker rm</b> removes only the container instance, not the image it was created from. Images require <b>docker rmi</b> for removal.<br><br><I>Dependencies:</I> Containers might be dependent on other containers (e.g., through networking). Removing a dependent container might affect others.


title: REMOVING ALL EXITED CONTAINERS
content:
To quickly remove all stopped containers, one can combine <b>docker rm</b> with <b>docker ps -aq</b>. The command is <b>docker rm $(docker ps -aq)</b>. This is a common pattern for clearing development environments.


title: AUTOMATIC REMOVAL ON EXIT
content:
For temporary containers, the <b>--rm</b> flag can be used when starting a container (e.g., <b>docker run --rm ...</b>). This automatically removes the container once it exits, eliminating the need for a separate <b>docker rm</b> command.


title: HISTORY
content:
The <b>docker rm</b> command has been a core part of the Docker CLI since its early days, essential for managing container lifecycles and disk space. Its functionality has remained largely consistent, reflecting its straightforward purpose of deleting container instances. While Docker's networking and volume management have evolved significantly, <b>docker rm</b> continues to provide the fundamental cleanup mechanism for individual containers, often used in conjunction with other commands for comprehensive system maintenance.


title: SEE ALSO
content:
docker stop(1), docker kill(1), docker ps(1), docker rmi(1), docker volume rm(1), docker network rm(1), docker system prune(1)


title: DESCRIPTION
content:
The <i>docker container rename</i> command is a fundamental Docker CLI utility used to change the name of an existing container. This operation allows users to assign a more descriptive, mnemonic, or convenient name to a container after its creation. Renaming is particularly useful for improving the manageability and identification of containers, especially in environments with numerous running instances. The command takes two primary arguments: the current name or ID of the container to be renamed, and the desired new name. It's important to note that the new name must be unique among all containers managed by the Docker daemon; if a container with the specified new name already exists, the command will fail. This flexibility enables users to rename both running and stopped containers without affecting their internal state, configuration, or allocated resources, simplifying container orchestration and enhancing readability when listing containers.


title: CAVEATS
content:
The <i>NEW_NAME</i> must be unique across all containers managed by your Docker daemon; attempting to use an already existing name will result in an error. Renaming a container does not change its unique ID or its internal configuration, only its externally referenced name. While renaming can be performed on both running and stopped containers, for containers part of orchestrated systems like Docker Compose or Swarm, it is generally recommended to modify the service definition rather than manually renaming individual containers to maintain consistency and avoid unexpected behavior.


title: ALIASES
content:
For backward compatibility and user convenience, <i>docker rename</i> acts as an alias for <i>docker container rename</i>. Both commands perform the identical operation.


title: ARGUMENTS
content:
The command requires two positional arguments: <i>OLD_NAME</i>, which can be the container's current name or its short/long ID, and <i>NEW_NAME</i>, the desired unique name for the container.


title: HISTORY
content:
The ability to rename containers has been a core feature of the Docker CLI since its early development, reflecting the need for flexible container management. Initially available as <i>docker rename</i>, the command was later aliased by <i>docker container rename</i> with the introduction of Docker Engine 1.13. This change was part of a broader initiative to restructure the Docker CLI, grouping subcommands under specific object types (e.g., <i>container</i>, <i>image</i>, <i>network</i>). This reorganization aimed to create a more consistent, intuitive, and scalable command-line interface, making it easier for users to discover and utilize commands as the Docker platform grew in complexity and capability.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the removal of a running container. Uses <i>SIGKILL</i> to stop the container first.<br><br><b><b>-l</b>, <b>--link</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the specified link. (Primarily for legacy container linking, not common for general <b>docker rm</b> use).<br><br><b><b>-v</b>, <b>--volumes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the anonymous volumes associated with the container. Named volumes are not affected.<br><br>


title: DESCRIPTION
content:
The <i>docker rm</i> command is used to remove one or more stopped Docker containers from a host. By default, it will only remove stopped containers. To remove a running container, the <br><i>--force</i> (or <i>-f</i>) option must be used, which sends a <i>SIGKILL</i> signal to the container before attempting removal. <br>This command is crucial for freeing up system resources, such as disk space and memory, consumed by containers that are no longer needed. When a container is removed, its writable layer is deleted. However, volumes attached to the container are not removed by default. To also remove anonymous volumes associated with the container, the <br><i>--volumes</i> (or <i>-v</i>) option can be specified. Named volumes and host-mounted volumes require separate commands for removal.


title: CAVEATS
content:
Cannot remove a <i>running</i> container without the <b>--force</b> (<b>-f</b>) option. Using <b>-f</b> will terminate the container immediately without giving it a chance to gracefully shut down.<br>By default, <i>named volumes</i> and <i>host-mounted volumes</i> are <b>not</b> removed when a container is deleted, even with the <b>-v</b> option. These must be managed separately using <b>docker volume rm</b>.<br>Associated <i>networks</i> and <i>images</i> used by the container are not removed by <b>docker rm</b>. These must be cleaned up independently using <b>docker network rm</b> or <b>docker rmi</b> respectively.<br>Removing a container does not remove its <i>parent image</i> or any <i>child containers</i> it might have spawned. The container's history and configuration are lost upon removal.


title: REMOVING ALL STOPPED CONTAINERS
content:
To remove all stopped containers, a common pattern involves combining <b>docker ps -aq</b> (which lists all container IDs, including stopped ones, in quiet mode) with <b>docker rm</b>. For example:<br><b>docker rm</b> $(<b>docker ps -aq</b>)<br>This command should be used with caution as it will attempt to remove all containers, whether stopped or not, potentially leading to errors for running ones unless <b>-f</b> is added to the <b>docker rm</b> command.


title: DISTINCTION FROM DOCKER STOP/KILL
content:
While <b>docker stop</b> and <b>docker kill</b> are used to halt a running container, <b>docker rm</b> is specifically for deleting the container's instance from the Docker daemon. A stopped or killed container still exists on the system and consumes disk space; it needs to be <i>removed</i> to free up those resources. Think of it as 'shutting down' vs. 'deleting the machine'.


title: HISTORY
content:
The <b>docker rm</b> command has been a fundamental part of the Docker CLI since its early days, reflecting the crucial need for container lifecycle management and resource cleanup. As Docker evolved from a niche technology to a mainstream platform for containerization, the ability to efficiently remove containers became paramount for maintaining clean development environments, managing CI/CD pipelines, and ensuring robust production systems. Its design emphasizes explicit control: containers are not automatically removed to prevent accidental data loss, placing the responsibility on the user to manage cleanup. The addition of options like <b>-v</b> and the development of broader cleanup commands like <b>docker system prune</b> showcase the growing maturity of Docker's resource management capabilities over time.


title: SEE ALSO
content:
<b>docker ps</b>(1), <b>docker stop</b>(1), <b>docker kill</b>(1), <b>docker rmi</b>(1), <b>docker volume rm</b>(1), <b>docker system prune</b>(1)


title: PARAMETERS
content:
<b>CONTAINER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The name or ID of the running container for which to display processes. This is a mandatory argument.</i><br><br><b>[ps OPTIONS]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional arguments to pass directly to the `ps` command executed inside the container. These options control the format and columns of the output. For example, `aux` for detailed output or `-ef` for a full format listing. The availability and behavior of these options depend on the `ps` utility installed within the container's image.</i><br><br>


title: DESCRIPTION
content:
The <b>docker top</b> command allows users to view the running processes inside a specific Docker container. It functions similarly to the <b>top</b> or <b>ps</b> command on a Linux host, but operates within the isolated environment of a container. This is crucial for debugging, monitoring, and understanding resource consumption of applications running within containers. It displays process ID (PID), user, CPU usage, memory usage, and the command line that initiated the process, providing insights into the container's operational state. This command is particularly useful for diagnosing issues where a container might be consuming excessive resources or for verifying that expected processes are running correctly.


title: CAVEATS
content:
<i><br><b>Container Must Be Running:</b> The command can only display processes for containers that are currently in a running state. If the container is stopped, an error will occur.<br><b>`ps` Utility Dependency:</b> `docker top` relies on the `ps` utility being present and executable within the container's file system. Minimalistic base images might not include `ps`, leading to an error or an incomplete output.<br><b>Snapshot vs. Real-time:</b> This command provides a snapshot of processes at the moment of execution. For continuous, real-time monitoring of resource usage, `docker stats` is a more appropriate tool.<br><b>PID Namespace:</b> The PIDs displayed are specific to the container's PID namespace, meaning PID 1 inside the container is the initial process of that container, not PID 1 of the host system.</i>


title: INTERNAL `PS` COMMAND EXECUTION
content:
<i>The `docker top` command functions by essentially executing the `ps` utility within the target container's isolated environment. This means that the processes listed are those visible from inside the container's perspective, and the columns displayed (e.g., USER, PID, CPU, MEM, COMMAND) are determined by the version and configuration of `ps` installed within that specific container image. The output format and available options are therefore subject to the container's internal `ps` utility.</i>


title: COMMON `PS` OPTIONS
content:
<i>While `docker top` itself has minimal options, its power comes from passing standard `ps` options directly to the command executed inside the container. Common examples include `<b>docker top my-container aux</b>` for a full listing of processes with user, CPU, and memory, or `<b>docker top my-container -ef</b>` for a standard full-format listing, which can reveal process trees and environmental variables if supported by the container's `ps`.</i>


title: HISTORY
content:
<i>The command was originally named `docker-container-top` in earlier versions of Docker, clearly indicating its operation on containers. As Docker evolved and its command-line interface was streamlined for better user experience and consistency, it was shortened to `docker top`. This simplification made the command more intuitive and aligned with other top-level Docker commands like `docker ps` and `docker logs`, while maintaining its core functionality of inspecting container processes.</i>


title: SYNOPSIS
content:
The 'docker-containers' concept does not have a single command synopsis as it represents a collection of <i>docker</i> subcommands. Here are synopses for two of the most fundamental operations related to Docker containers:<br><br><b>1. Listing Containers:</b><br> <i>docker ps</i> [<i>OPTIONS</i>]<br><br><b>2. Running a New Container:</b><br> <i>docker run</i> [<i>OPTIONS</i>] <i>IMAGE</i> [<i>COMMAND</i>] [<i>ARG</i>...]


title: PARAMETERS
content:
<b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker ps</i>: Show all containers (default shows just running ones).<br><br><b>-d, --detach</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker run</i>: Run container in the background and print the container ID.<br><br><b>-it</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker run</i>: Allocate a pseudo-TTY and keep stdin open, commonly used for interactive shells.<br><br><b>--name string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker run</i>: Assign a specific name to the container.<br><br><b>-p, --publish list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker run</i>: Publish a container's port(s) to the host's ports.<br><br><b>--rm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker run</i>: Automatically remove the container when it exits.<br><br><b>--format string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>docker ps</i>: Pretty-print containers using a Go template for custom output.<br><br>


title: DESCRIPTION
content:
The term "docker-containers" does not refer to a standalone Linux command. Instead, it serves as a conceptual grouping for the various subcommands within the <i>docker</i> CLI that are used to manage the lifecycle of <B>Docker containers</B>. A Docker container is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings. <br><br>Docker provides a robust set of tools for interacting with containers, allowing users to <B>run</B> new containers, <B>list</B> running or exited containers, <B>stop</B> active containers, <B>start</B> stopped ones, <B>remove</B> containers, and inspect their properties or logs. These operations are performed using the main <i>docker</i> command followed by a specific subcommand (e.g., <i>docker run</i>, <i>docker ps</i>, <i>docker stop</i>, <i>docker rm</i>). The underlying technology leverages Linux kernel features like namespaces and cgroups to isolate processes.


title: CAVEATS
content:
The primary caveat is that 'docker-containers' is not an executable command itself. All interactions with Docker containers are done via the <i>docker</i> CLI tool and its various subcommands. Users must have Docker installed and the Docker daemon running to perform any container operations. Commands often require appropriate user permissions (e.g., being part of the 'docker' group or using <i>sudo</i>).


title: CONTAINER LIFECYCLE
content:
Docker containers transition through various states: <br><b>Created:</b> The container has been created but not started. <br><b>Running:</b> The container is actively executing its primary process. <br><b>Paused:</b> The container's processes have been suspended. <br><b>Stopped/Exited:</b> The container's primary process has finished or been terminated; it still exists on disk. <br><b>Removed:</b> The container has been deleted from the system.


title: CONTAINER VS. IMAGE
content:
An <B>Image</B> is a read-only template with instructions for creating a Docker container. It's like a blueprint for an application. A <B>Container</B> is a runnable instance of an image. You can create, start, stop, move, or delete a container. Multiple containers can be run from the same image, each isolated from the others.


title: HISTORY
content:
The concept of containers has existed for decades in various forms (e.g., FreeBSD Jails, Solaris Zones, Linux VServer, LXC). However, the modern surge in containerization was largely ignited by the release of <B>Docker in 2013</B>. Docker simplified the packaging, distribution, and running of applications in isolated environments, making container technology accessible and widely adopted. Its user-friendly CLI and image management system rapidly popularized the use of Linux containers, leading to a paradigm shift in software development and deployment methodologies, especially within DevOps practices and cloud-native architectures.


title: SYNOPSIS
content:
docker context COMMAND<br>docker context [OPTIONS] COMMAND<br><br>Common Commands:<br>docker context create [OPTIONS] CONTEXT<br>docker context ls [OPTIONS]<br>docker context use CONTEXT<br>docker context inspect [OPTIONS] [CONTEXT...]<br>docker context rm [OPTIONS] CONTEXT [CONTEXT...]


title: PARAMETERS
content:
<b>create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new Docker context.<br><br><b>export</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Export a context to a tar file.<br><br><b>import</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Import a context from a tar file.<br><br><b>inspect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information on one or more contexts.<br><br><b>ls</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List Docker contexts.<br><br><b>rm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove one or more contexts.<br><br><b>use</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the current Docker context.<br><br><b>update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update a context.<br><br>


title: DESCRIPTION
content:
<br>The <b>docker context</b> command group is part of the Docker CLI, designed to manage connections to different Docker daemons. A "Docker context" encapsulates the configuration needed to connect your Docker CLI to a specific Docker host or cluster. This can be a local Docker Desktop instance, a remote Docker Engine running on a cloud VM, a Docker Swarm cluster, or even integration with Kubernetes, Azure Container Instances (ACI), or Amazon Elastic Container Service (ECS) via Docker Desktop.<br><br>It enables users to seamlessly switch between various development, testing, and production environments without manually changing environment variables or complex configurations. Key functionalities include creating new contexts, listing existing ones, switching the active context, inspecting context details, and removing contexts.


title: CAVEATS
content:
Contexts abstract connection details, but underlying network access (firewall, SSH, VPN) must still be correctly configured.<br>Switching contexts affects all subsequent Docker commands in the current shell session, which can lead to accidental operations on the wrong environment if not mindful.<br>Managing many contexts can become complex; naming conventions are important.


title: DEFAULT CONTEXT
content:
<br>The default context is usually named <i>"default"</i> and points to the local Docker daemon (e.g., Docker Desktop or a local Linux installation).


title: CONTEXT TYPES
content:
<br>Contexts can be configured for various backends, including:<br><i>docker</i>: Standard Docker Engine (local or remote via TCP/SSH).<br><i>kubernetes</i>: Connects to a Kubernetes cluster (often integrated via Docker Desktop's Kubernetes feature).<br><i>aci</i>: Azure Container Instances (via Docker Desktop).<br><i>ecs</i>: Amazon Elastic Container Service (via Docker Desktop).


title: USING A CONTEXT
content:
<br>To switch to a context named <i>my_remote_server</i>:<br>`docker context use my_remote_server`<br><br>To run a single command with a specific context without changing the default:<br>`docker --context my_remote_server ps`


title: HISTORY
content:
Docker contexts were introduced in Docker Engine 19.03 (2019) to provide a more streamlined and integrated way of managing connections to different Docker daemons, especially in hybrid cloud and multi-cluster environments. Prior to contexts, users typically managed connections via the <b>DOCKER_HOST</b> environment variable or Docker Machine. Contexts offer a more robust, persistent, and user-friendly mechanism to switch between environments, including direct integration with Kubernetes, ACI, and ECS through Docker Desktop.


title: SYNOPSIS
content:
<i>docker cp</i> [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-<br><i>docker cp</i> [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH<br><br><i>Arguments:</i><br><b>CONTAINER:</b> The name or ID of the container.<br><b>SRC_PATH:</b> The source path on the host or inside the container.<br><b>DEST_PATH:</b> The destination path on the host or inside the container.<br><b>-</b> (hyphen): Represents standard input or standard output for streaming operations.


title: PARAMETERS
content:
<b><b>--archive</b>, <b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve UID:GID and permissions. Behaves like <i>tar -p</i>.<br><br><b><b>--follow-link</b>, <b>-L</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Always follow symbolic link in SRC_PATH.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print usage statement.<br><br>


title: DESCRIPTION
content:
<i>docker cp</i> is a fundamental command in the Docker CLI that facilitates the transfer of files and directories between a host machine and a running Docker container, or vice versa. It provides a convenient way to get data out of a container (e.g., logs, configuration files, output data) or to put data into a container (e.g., application code, static assets, scripts) without needing to mount volumes or use more complex methods like <i>docker exec</i> with <i>tar</i>. The command supports specifying paths on both the host and within the container. When copying from the host to the container, if the destination path does not exist, <i>docker cp</i> creates it. If the destination is a directory, the source is copied inside it. When copying from the container, it preserves file attributes and ownership to some extent, though this can be controlled with options. It's an essential tool for debugging, development, and managing containerized applications.


title: CAVEATS
content:
<i>docker cp</i> operates directly on the container's filesystem layer, bypassing any mounted volumes. This means if you copy a file to a path that is also a volume mount point, the file will be written to the container's writeable layer and not to the underlying volume itself. Permissions and ownership of copied files can sometimes be tricky: by default, it attempts to preserve them, but the destination user/group IDs might not match the source. When copying to a container, files are owned by <i>root:root</i> if no specific user is defined in the container's image or run configuration. Using wildcards in paths (e.g., <i>*.txt</i>) on the host side requires shell expansion; <i>docker cp</i> does not interpret them directly. For robust and complex file transfers, especially with large amounts of data, using <i>docker exec</i> with <i>tar</i> and piping (e.g., <i>tar -c . | docker exec -i mycontainer tar -x -C /dest</i>) is often more reliable and efficient.


title: <B>PERMISSIONS AND OWNERSHIP HANDLING</B>
content:
When copying files from the host to a container, <i>docker cp</i> by default sets the ownership to <i>root:root</i> inside the container, unless the container is running as a different user or the <i>--archive</i> option is used. With <i>--archive</i> (or <i>-a</i>), <i>docker cp</i> attempts to preserve the original ownership (UID and GID) and permissions. However, if the UID/GID does not exist within the container, the files might appear with numeric IDs.


title: <B>STREAMING WITH STANDARD I/O (-)</B>
content:
The hyphen (<B>-</B>) can be used as a special path to represent standard input or standard output. For example, to copy a file from a container and pipe it to another command on the host: <i>docker cp mycontainer:/app/logs.txt - | less</i>. To pipe content from standard input on the host into a file in the container: <i>cat myconfig.txt | docker cp - mycontainer:/app/config.txt</i>. This allows for flexible and efficient data transfer without intermediate files.


title: <B>DIRECTORY COPY BEHAVIOR</B>
content:
When copying a directory, <i>docker cp</i> copies the directory's contents. If the source is a directory <i>/path/to/dir</i> and the destination is <i>/new/dest</i>, it behaves like <i>cp -a /path/to/dir/. /new/dest</i>, meaning the contents of <i>dir</i> are copied into <i>/new/dest</i>. If you want to copy the directory itself (i.e., <i>/new/dest/dir</i> will be created), you need to specify the source with a trailing slash or the parent directory.


title: HISTORY
content:
The <i>docker cp</i> command has been a core feature of the Docker CLI since its early days, reflecting the fundamental need to interact with container filesystems for development, debugging, and data extraction. Its inclusion underscores Docker's commitment to providing intuitive tools for container management. Over time, its functionality has remained largely consistent, with minor improvements focusing on handling permissions, symlinks, and providing the <i>--archive</i> option for more faithful file attribute preservation. It has become an indispensable command for anyone working with Docker containers.


title: PARAMETERS
content:
<b>-f, --format string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print diff using a Go template. This allows for custom output formatting based on the Go template syntax.<br><br><b>--no-trunc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not truncate output. By default, output might be truncated for readability, but this option ensures full paths and other details are displayed.<br><br>


title: DESCRIPTION
content:
<i>docker diff</i> is a powerful command-line utility within the Docker ecosystem that allows users to examine changes made to the filesystem of a running or stopped container. It provides a concise summary of files and directories that have been added, modified, or deleted within the container's writable layer since it was created or started.<br><br>This command is invaluable for debugging containerized applications, understanding the runtime state of a container, and verifying immutability. For instance, if an application unexpectedly creates files or modifies configurations, <i>docker diff</i> can quickly highlight these changes. It operates by comparing the current state of the container's filesystem with its original base image layers. The output is typically presented as a list of paths prefixed with 'A' (Added), 'C' (Changed), or 'D' (Deleted), indicating the type of modification. Understanding these differences is crucial for maintaining clean container images and troubleshooting unexpected behavior.


title: CAVEATS
content:
<i>docker diff</i> focuses solely on the container's <b>writable layer</b>. This implies several limitations:<br><br><i><b><br>• Volumes Ignored:</b></i> It will <b>not</b> show any changes made within <b>mounted volumes</b> (e.g., bind mounts, named volumes). Changes in volumes reside outside the container's filesystem layering and are not tracked by this command.<br><br><i><b><br>• Snapshot in Time:</b></i> The output reflects differences relative to the container's initial state (when it was created from an image) or its last commit. It does not provide a historical log of every single change made over time, only the net differences.<br><br><i><b><br>• Abstraction of Contents:</b></i> While it lists changed files, it does not show the actual content differences (like a traditional <i>diff</i> utility). For content comparison, you would typically need to copy the files out of the container.


title: OUTPUT CODES EXPLAINED
content:
The output of <i>docker diff</i> uses single-character prefixes to denote the type of change:<br><br><i><b><br>• A: Added</b></i> - A file or directory has been newly created within the container's writable layer.<br><br><i><b><br>• C: Changed</b></i> - An existing file or directory within the container's writable layer has been modified (e.g., content altered, permissions changed).<br><br><i><b><br>• D: Deleted</b></i> - A file or directory that existed in a lower layer (or was previously created in the writable layer) has been removed.


title: UNDERSTANDING THE LAYERED FILESYSTEM
content:
<i>docker diff</i> is intrinsically linked to Docker's <b>copy-on-write</b> (CoW) layered filesystem. When a container is started, it gets a thin, writable layer on top of its read-only image layers. All modifications (additions, changes, deletions) made by the container at runtime are recorded in this writable layer. <i>docker diff</i> essentially reports on the contents of this top-most writable layer relative to the layers below it, providing visibility into the state changes specific to that container instance.


title: HISTORY
content:
The <i>docker diff</i> command has been an integral part of the Docker Command Line Interface (CLI) since the early versions of the Docker engine. Its inclusion reflects the fundamental need for developers and operators to understand the runtime state and modifications occurring within containerized environments. It is not a standalone utility but rather a core function bundled with the main <i>docker</i> client, evolving alongside the Docker platform itself to provide insights into its layered filesystem architecture. Its stability and consistent functionality highlight its foundational role in Docker diagnostics and management.


title: PARAMETERS
content:
<b><b>-d</b>, <b>--detach</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the command in detached mode (background).<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep STDIN open even if not attached. Often used with <b>-t</b> for interactive sessions.<br><br><b><b>-t</b>, <b>--tty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allocate a pseudo-TTY. Often used with <b>-i</b> to provide an interactive shell experience.<br><br><b><b>-u</b>, <b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the username or UID (and optional group/GID) to run the command as (e.g., <i><name|uid>[:<group|gid>]</i>).<br><br><b><b>-e</b>, <b>--env</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set environment variables for the command (e.g., <b>-e "VAR=value"</b>). Can be used multiple times.<br><br><b><b>--env-file</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read environment variables from a file in <i>KEY=VALUE</i> format.<br><br><b><b>--privileged</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Give extended privileges to the command inside the container (use with caution).<br><br><b><b>-w</b>, <b>--workdir</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the working directory inside the container for the command.<br><br>


title: DESCRIPTION
content:
<b>docker exec</b> provides a powerful way to run new commands within an already running Docker container. Unlike <b>docker run</b>, which initiates a new container, <b>docker exec</b> operates on an existing, active container process. This capability is indispensable for debugging, inspecting, or performing administrative tasks directly within a container's isolated environment without the need to stop or restart it. It can execute commands interactively, such as spawning a shell (<i>bash</i> or <i>sh</i>), or in detached mode for background operations. Users commonly leverage <b>docker exec</b> to access a container's file system, install software, check application status, or modify configurations, making it a cornerstone tool for container lifecycle management and troubleshooting.


title: CAVEATS
content:
The target container must be in a <i>running</i> state for <b>docker exec</b> to function.<br>Commands executed with <b>docker exec</b> run as new processes within the container, separate from its primary PID 1 process.<br>Exercise caution when using <b>--privileged</b> or running commands as <i>root</i> (<b>-u 0</b>) due to potential security risks.<br>If the specified <i>COMMAND</i> does not exist within the container's environment, the <b>docker exec</b> call will fail.


title: INTERACTIVE SHELL ACCESS
content:
The most common use case for <b>docker exec</b> is gaining an interactive shell inside a container, typically via <b>docker exec -it <i><container_name_or_id></i> bash</b> (or <i>sh</i>). This allows users to navigate the filesystem, run diagnostics, and debug applications as if directly logged into the container's environment.


title: NON-INTERACTIVE USE CASES
content:
<b>docker exec</b> is also highly effective for running single, non-interactive commands. Examples include <b>docker exec mycontainer ls -l /app</b> to list files, or <b>docker exec -d mycontainer sh -c "sleep 3600 && echo 'Task done'"</b> for executing background tasks.


title: KEY DISTINCTION WITH DOCKER RUN
content:
It's crucial to differentiate <b>docker exec</b> from <b>docker run</b>. While both execute commands, <b>docker run</b> creates and starts a <i>new</i> container for the command, whereas <b>docker exec</b> runs a command <i>within an already existing and running</i> container.


title: HISTORY
content:
<b>docker exec</b> was introduced in Docker to address the critical need for interacting with running containers dynamically. Prior to its existence, debugging or making on-the-fly changes to a container often required stopping it, making modifications, and then restarting, or resorting to more cumbersome methods like <b>docker commit</b>. Its inclusion significantly streamlined development and operational workflows by enabling direct, non-disruptive access, quickly establishing it as an indispensable command for container management.


title: SYNOPSIS
content:
<b>docker image</b> <I>COMMAND</I> [<I>OPTIONS</I>]<br>Examples:<br><b>docker image ls</b> [<I>OPTIONS</I>]<br><b>docker image pull</b> <I>NAME[:TAG]</I><br><b>docker image rm</b> <I>IMAGE</I> [<I>IMAGE...</I>]<br><b>docker image build</b> [<I>OPTIONS</I>] <I>PATH | URL</I>


title: PARAMETERS
content:
<b>ls | images</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all Docker images available locally, often showing repository, tag, image ID, creation time, and size.<br><br><b>pull <I>NAME[:TAG]</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Download an image or a repository from a remote registry (e.g., Docker Hub) to your local system.<br><br><b>build [<I>OPTIONS</I>] <I>PATH | URL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Construct a new image from a Dockerfile and a specified build context (usually a directory containing the Dockerfile and source files).<br><br><b>rm | rmi <I>IMAGE</I> [<I>IMAGE...</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove one or more images by their ID or name. This command requires the image to not be in use by any running containers.<br><br><b>inspect <I>IMAGE</I> [<I>IMAGE...</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed low-level information about one or more images, including configuration, layers, and metadata, often in JSON format.<br><br><b>tag <I>SOURCE_IMAGE[:TAG]</I> <I>TARGET_IMAGE[:TAG]</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new tag for an existing image. This allows referring to the same image with a different name or version.<br><br><b>push <I>NAME[:TAG]</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upload an image or a repository from your local system to a remote registry, making it available for others to pull.<br><br><b>prune</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all dangling images (those that are not tagged and not referenced by any container) and optionally all unused images.<br><br>


title: DESCRIPTION
content:
The `docker image` command provides comprehensive functionality for managing Docker images on a system. Images are read-only templates used to create Docker containers. This command allows users to perform various operations such as listing all local images, pulling images from a registry like Docker Hub, building new images from a Dockerfile, tagging images with different names or versions, removing unwanted images to free up disk space, inspecting image details, and pushing images to a remote registry. It is an essential part of the Docker workflow, enabling the creation, distribution, and lifecycle management of containerized applications. Understanding and effectively utilizing `docker image` is fundamental for anyone working with Docker.


title: CAVEATS
content:
The `docker image` command is a subcommand of `docker`; it must be invoked as `docker image` and not as a standalone executable. Image removal (`docker image rm`) can fail if there are active containers or other images dependent on the image. Building images (`docker image build`) requires a Dockerfile and a build context; large contexts or inefficient Dockerfiles can significantly impact build times and image sizes. Heavy image usage can consume substantial disk space, necessitating regular cleanup with `docker image prune`.


title: IMAGE LAYERS AND CACHING
content:
Docker images are constructed from a series of read-only layers. Each instruction in a Dockerfile typically generates a new layer. This layered architecture enables efficient caching during image builds, as unchanged layers can be reused from previous builds, significantly speeding up development. It also optimizes storage, allowing multiple images to share common underlying layers, thus reducing overall disk space usage.


title: IMAGE MANIFESTS
content:
Beyond just layers, a Docker image is described by an image manifest. This is a JSON document that specifies crucial details about the image, such as its architecture (e.g., `amd64`, `arm64`), operating system, and a list of its constituent layers. The manifest is vital for Docker to correctly pull and run images on different system architectures and for verifying the image's integrity and content.


title: HISTORY
content:
Docker was initially released in March 2013. The `docker image` subcommand structure was introduced as part of Docker's continuous efforts to modularize and organize its command-line interface. Prior to this, image-related operations like `docker images`, `docker rmi`, `docker pull`, and `docker build` were top-level commands. This shift, along with the introduction of `docker container`, `docker network`, and `docker volume` subcommands, aimed to create a more intuitive and hierarchical CLI, improving discoverability and consistency for users managing various Docker components as the platform matured and its feature set expanded.


title: SYNOPSIS
content:
<b>docker images</b> <i>[OPTIONS] [REPOSITORY[:TAG]]</i><br>The <i>[REPOSITORY[:TAG]]</i> part is an optional positional argument used to filter images by a specific repository name and/or tag.


title: PARAMETERS
content:
<b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all images, including intermediate layers. By default, only top-level images are displayed.<br><br><b>--digests</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show image digests (SHA256 checksums) in the output.<br><br><b>-f, --filter filter</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter output based on various conditions. Common filters include 'dangling=true' (for untagged images), 'label=<key>=<value>', 'reference=<repo[:tag]>', 'before=<image>', 'since=<image>', 'size=<size>', etc.<br><br><b>--format string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print images using a Go template, allowing customized output. For example: '{{.ID}}\t{{.Repository}}\t{{.Size}}'.<br><br><b>--no-trunc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not truncate output. Image IDs and other fields will be displayed in full.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only display numeric IDs (Image IDs) of the images, suppressing all other columns.<br><br>


title: DESCRIPTION
content:
The <b>docker images</b> command (also accessible as <b>docker image ls</b>) is a fundamental Docker CLI utility used to list Docker images available on the local system. It provides a comprehensive overview of images, including their repository name, tag, unique image ID, the date and time they were created, and their virtual size. This command is essential for managing your local image cache, identifying images to be removed, verifying successful image builds, or simply inspecting what images you have downloaded or created. It displays both top-level images and optionally, all intermediate image layers.


title: CAVEATS
content:
Images consume significant disk space; regularly inspect and remove unused images using <b>docker rmi</b> or <b>docker prune</b>. <i>Dangling images</i> (untagged images not referenced by any container) can accumulate and waste space. They can be found using <b>docker images -f "dangling=true"</b> and removed with <b>docker rmi $(docker images -f "dangling=true" -q)</b> or more easily with <b>docker image prune</b>.


title: FILTERING EXAMPLES
content:
To show only dangling images: <b>docker images -f "dangling=true"</b><br>To show images larger than 1GB: <b>docker images -f "size=1G"</b><br>To show images by a specific label: <b>docker images -f "label=version=1.0"</b>


title: CUSTOM OUTPUT FORMATTING
content:
Using <b>--format</b> allows precise control over the output columns and their presentation, useful for scripting.<br>Example: <b>docker images --format "{{.ID}}\t{{.Repository}}\t{{.Tag}}\t{{.Size}}"</b><br>This command would output the image ID, repository, tag, and size, separated by tabs.


title: REPOSITORY AND TAG FILTERING
content:
You can append a <i>REPOSITORY[:TAG]</i> argument to the command to narrow down the displayed images.<br>Example: <b>docker images ubuntu</b> (lists all <i>ubuntu</i> images)<br>Example: <b>docker images nginx:latest</b> (lists the specific <i>nginx:latest</i> image)


title: HISTORY
content:
The <b>docker images</b> command has been a core part of the Docker CLI since its early days, providing a straightforward way to inspect local images. While <b>docker image ls</b> was introduced as part of the more structured <i>docker &lt;object&gt; &lt;command&gt;</i> syntax (e.g., <i>docker container ls</i>, <i>docker volume ls</i>), <b>docker images</b> remains fully functional and widely used for its familiarity and brevity.


title: PARAMETERS
content:
<b>--format, -f <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format the output using a Go template. This is highly flexible for extracting specific data points from the extensive JSON output.<br><br><b>--size, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display total file sizes if the object is a container. Useful for understanding disk usage.<br><br><b>--type <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Return JSON for a specific type of object (e.g., <I>container</I>, <I>image</I>, <I>network</I>, <I>volume</I>). Helps narrow down the scope when an ID could potentially refer to multiple object types.<br><br>


title: DESCRIPTION
content:
The <I>docker inspect</I> command provides a raw, low-level view of an object's configuration and state as maintained by the Docker daemon.<br>This command is incredibly useful for debugging, scripting, and automation, as it outputs information in JSON format by default, making it easily parsable by other tools.<br>It can inspect various Docker objects, including <B>containers</B>, <B>images</B>, <B>networks</B>, <B>volumes</B>, and <B>plugins</B>, by specifying their name or ID.<br>The output includes extensive metadata such as network settings, mounted volumes, container state, image layers, and more.<br>Users can also customize the output using <B>Go templates</B> via the <I>--format</I> option, allowing for extraction of specific data points rather than the entire verbose JSON structure. This makes it a powerful tool for integrating Docker information into scripts and applications.


title: CAVEATS
content:
The output can be extremely verbose and contain a large amount of data, which might be overwhelming for direct human consumption without piping to a JSON formatter like <I>jq</I>.<br>Care should be taken when sharing <I>docker inspect</I> output as it may contain sensitive configuration details, environment variables, or IP addresses.<br>Extracting specific data with Go templates can have a learning curve due to the template syntax.


title: GO TEMPLATE USAGE
content:
The <I>--format</I> option is key for automation and selective data retrieval. For instance, to get a container's IP address: <B>docker inspect -f '{{.NetworkSettings.IPAddress}}' mycontainer</B>.<br>To check if a container is running: <B>docker inspect -f '{{.State.Running}}' mycontainer</B>.<br>You can iterate over arrays, e.g., to list all mounted volumes: <B>docker inspect -f '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{end}}' mycontainer</B>.<br>Templates support conditional logic, loops, and functions, allowing for complex data extraction and formatting.


title: INSPECTING MULTIPLE OBJECTS
content:
You can inspect multiple objects in a single command by providing multiple names or IDs, like <B>docker inspect container1 container2 image-id</B>. The output will be a JSON array containing the detailed information for each specified object, making it efficient for batch processing.


title: HISTORY
content:
<I>docker inspect</I> has been a core utility since the early days of Docker's public release around 2013. As Docker revolutionized containerization, the need for a granular understanding of container and image internals became paramount. <I>inspect</I> was designed to provide exactly that, offering a programmatic interface to the metadata stored by the Docker daemon. Its JSON output format aligned well with the rise of automation and scripting, making it an indispensable command for developers and operations teams alike. It has evolved with Docker, accommodating new object types like volumes and plugins.


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show help for the command</I><br><br><b>-i, --input <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Read from tar archive file, instead of STDIN</I><br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Suppress the load output, only show image IDs</I><br><br>


title: DESCRIPTION
content:
The <b>docker load</b> command is used to load images and their associated metadata (like layers and tags) from a tar archive into the Docker image store. This archive is typically created using the <b>docker save</b> command. It's a crucial tool for transferring Docker images between environments, especially in offline or air-gapped scenarios, as it encapsulates the entire image filesystem and configuration into a single portable file.<br><br>Unlike <b>docker import</b>, which creates a new image from a tarball of a filesystem (without history or layers), <b>docker load</b> preserves the full image history, layers, and multiple tags. This ensures that the loaded image is identical to the one that was saved, making it suitable for disaster recovery, versioning, and distribution without relying on a remote registry.


title: CAVEATS
content:
The input must be a tar archive containing Docker images, typically created by <b>docker save</b>.<br><br>If an image with the same name and tag already exists in the local Docker image store, <b>docker load</b> will overwrite it. Be cautious when loading images that might conflict with existing ones.<br><br><b>docker load</b> does not verify the integrity or security of the loaded images; it simply imports them as provided.<br><br>It loads images into the local Docker daemon's image store; it does not automatically run or push these images to a registry.


title: INPUT SOURCE
content:
By default, <b>docker load</b> expects the tar archive to be piped to its standard input (e.g., <I>cat image.tar | docker load</I>). Alternatively, the <I>--input</I> or <I>-i</I> option can specify a file path (e.g., <I>docker load -i image.tar</I>).


title: IMAGE IDENTITY
content:
<b>docker load</b> preserves the image's full identity, including its layers, history, and all associated tags. This is in contrast to <b>docker import</b>, which creates a new image from a container's filesystem without its layered history.


title: USE CASES
content:
Ideal for distributing Docker images to environments without internet access or direct access to a Docker registry (air-gapped systems), backing up Docker images, or migrating images between Docker daemons on different hosts without relying on a registry.


title: HISTORY
content:
The <b>docker load</b> command has been a fundamental part of the Docker CLI since its early versions. It was introduced alongside <b>docker save</b> to provide a mechanism for offline image management, distribution, and backup, complementing the registry-based <b>docker pull</b> and <b>docker push</b> commands. Its core functionality has remained consistent, serving as a reliable method for transporting complete Docker images with their full layer history.


title: SEE ALSO
content:
docker save(1), docker import(1), docker export(1), docker images(1), docker push(1), docker pull(1)


title: PARAMETERS
content:
<b>CONTAINER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name or ID of the Docker container whose logs are to be fetched.<br><br><b>--details</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show extra details provided to the logs, such as environment variables or labels.<br><br><b>-f, --follow</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follow log output. This streams new logs as they are generated, similar to <b>tail -f</b>.<br><br><b>--since string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show logs only since a specific timestamp (e.g., '2013-01-01T13:23:37') or relative duration (e.g., '42m' for 42 minutes ago).<br><br><b>--tail string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number of lines to show from the end of the logs (e.g., '100' for the last 100 lines). By default, 'all' lines are shown.<br><br><b>-t, --timestamps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show timestamps for each log entry.<br><br><b>--until string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show logs only until a specific timestamp (e.g., '2013-01-01T13:23:37') or relative duration (e.g., '1h' for 1 hour ago).<br><br>


title: DESCRIPTION
content:
The <b>docker logs</b> command is a fundamental utility for interacting with Docker containers, allowing users to retrieve and display the output generated by a running or stopped container. It captures all data written to the container's <i>STDOUT</i> and <i>STDERR</i> streams. This command is invaluable for debugging applications, monitoring container health, and understanding the behavior of services within the Docker environment.<br><br>By default, Docker containers often use the <i>json-file</i> logging driver, which stores log data on the host filesystem. <b>docker logs</b> can display historical logs since the container's creation or stream new log entries in real-time, similar to the <b>tail -f</b> command. It supports filtering by timestamps, showing only recent entries, and can display full log lines without truncation. This capability makes <b>docker logs</b> an essential tool for operations, development, and troubleshooting in any Dockerized application stack.


title: CAVEATS
content:
<b>docker logs</b> relies on the container's configured logging driver. It works best with local drivers such as <i>json-file</i> (default) or <i>local</i>. If a container is configured to use an external logging driver (e.g., <i>syslog</i>, <i>fluentd</i>, <i>awslogs</i>), <b>docker logs</b> may not display any output, as logs are streamed directly to the external service. Furthermore, retrieving logs from containers with extremely large log files or during high I/O can be resource-intensive. Log rotation settings can also affect the availability of historical log data.


title: LOG DRIVERS
content:
Docker's logging drivers determine where container logs are sent. While <b>docker logs</b> primarily works with <i>json-file</i> and <i>local</i> drivers that store logs on the host, other drivers like <i>syslog</i>, <i>fluentd</i>, or <i>awslogs</i> direct logs to external services. Understanding the configured log driver is crucial when using <b>docker logs</b> to retrieve container output.


title: FILTERING AND PAGING
content:
For more advanced log analysis, the output of <b>docker logs</b> can be piped to other standard Linux utilities. For instance, <b>docker logs CONTAINER | grep "error"</b> can filter specific messages, and <b>docker logs CONTAINER | less</b> allows for interactive paging and searching through extensive log histories.


title: HISTORY
content:
The <b>docker logs</b> command has been an integral part of the Docker CLI since its early releases. Its functionality has remained consistently core to managing and debugging containers, focusing on retrieving <i>STDOUT</i> and <i>STDERR</i> streams. Over time, options like <i>--since</i>, <i>--tail</i>, and <i>--until</i> were added to enhance its capabilities for filtering and viewing specific log segments, making it more robust for diverse operational needs.


title: PARAMETERS
content:
<b><b>GLOBAL OPTIONS</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options that affect the overall behavior of the <i>docker-machine</i> command.<br><br><b><i>--debug</i>, <i>-D</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug mode, printing verbose output for troubleshooting.<br><br><b><i>--storage-path=&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path where machine configurations and certificates are stored. Defaults to <i>~/.docker/machine</i>.<br><br><b><i>--tls-skip-verify</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip TLS verification for the Docker daemon connection. Use with caution, as it bypasses security checks.<br><br><b><i>--github-api-token=&lt;token&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A GitHub API token used by certain drivers (e.g., to check for updates).<br><br><b><b>COMMANDS</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommands perform specific actions on Docker machines.<br><br><b><i>create &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a Docker host. Requires specifying a driver using <i>--driver</i> (e.g., <i>virtualbox</i>, <i>amazonec2</i>, <i>google</i>) and driver-specific options (e.g., <i>--virtualbox-memory</i>, <i>--amazonec2-instance-type</i>).<br><br><b><i>ls</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all managed Docker machines, showing their state, IP address, and Docker version. Accepts <i>--quiet</i> for names only or <i>--filter</i> for conditional listing.<br><br><b><i>start &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts one or more stopped Docker machines.<br><br><b><i>stop &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops one or more running Docker machines gracefully.<br><br><b><i>rm &lt;machine-name&gt; [flags]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes one or more Docker machines and their associated resources. Use <i>-f</i> or <i>--force</i> for forced removal without confirmation.<br><br><b><i>ssh &lt;machine-name&gt; [command]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a Docker machine via SSH. An optional <i>command</i> can be executed directly on the machine without an interactive session.<br><br><b><i>ip &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gets the IP address of a Docker machine.<br><br><b><i>env &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the commands required to set up the shell environment to interact with the Docker daemon on the specified machine. Typically used with <i>eval $(docker-machine env &lt;machine-name&gt;)</i>.<br><br><b><i>inspect &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a Docker machine in JSON format.<br><br><b><i>upgrade &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades the Docker client and daemon on a machine to the latest stable version.<br><br><b><i>config &lt;machine-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the connection configuration (e.g., DOCKER_HOST, DOCKER_TLS_VERIFY) for a machine.<br><br>


title: DESCRIPTION
content:
<i>docker-machine</i> is a command-line tool designed to provision and manage Docker hosts across various platforms. It can create Docker Engine-ready virtual machines on your local computer using hypervisors like VirtualBox, or on numerous cloud providers such as AWS, Azure, Google Cloud, and DigitalOcean. Once a machine is created, <i>docker-machine</i> provides commands to start, stop, restart, remove, and upgrade it. It also facilitates connecting to these machines via SSH, retrieving their IP addresses, and configuring your local Docker client to communicate with the Docker daemon running on the provisioned host.<br><br>This tool was particularly significant in enabling Docker's functionality on non-Linux operating systems (like macOS or Windows) before the advent of Docker Desktop, as it abstracted away the underlying VM management. While still functional, its primary role in local development has largely been superseded by more integrated solutions like Docker Desktop, and in production environments by cloud-native tools and container orchestration platforms.


title: CAVEATS
content:
<i>docker-machine</i> is considered largely superseded for local Docker development by <I>Docker Desktop</I> (for Windows/macOS/Linux) which provides a more integrated and user-friendly experience.<br><br>While still functional for provisioning remote Docker hosts, cloud providers' native CLI tools (e.g., <I>aws cli</I>, <I>gcloud cli</I>, <I>az cli</I>) and infrastructure-as-code solutions (e.g., Terraform) are often preferred for managing cloud-based VMs and their configurations due to greater flexibility and integration with broader cloud ecosystems. Its development activity has significantly slowed, and new features or drivers are rarely added.


title: CURRENT RELEVANCE AND ALTERNATIVES
content:
While <i>docker-machine</i> remains a powerful tool for provisioning Docker hosts, its direct relevance for day-to-day local Docker development has diminished. For macOS and Windows, <I>Docker Desktop</I> is the recommended and much simpler solution, as it bundles a lightweight VM and manages the Docker Engine transparently.<br><br>For cloud environments, direct interaction with cloud provider CLIs or robust infrastructure-as-code tools like Terraform are often preferred for their flexibility, scalability, and integration with broader cloud ecosystems. <i>docker-machine</i> might still be valuable for creating temporary, isolated Docker testing environments, for highly customized remote host provisioning where specific drivers are ideal, or for maintaining specific legacy setups that rely on its unique machine provisioning capabilities.


title: HISTORY
content:
<i>docker-machine</i> was introduced by Docker in 2015 as a key component of its strategy to bring Docker to non-Linux operating systems like macOS and Windows. Before its release, running Docker on these platforms typically required manually setting up a VirtualBox VM and configuring Docker.<br><br><i>docker-machine</i> automated this process, providing a consistent command-line interface to provision and manage these underlying Linux VMs that hosted the Docker Engine. Its importance in local development significantly decreased with the release of Docker for Mac and Docker for Windows (now collectively <I>Docker Desktop</I>) in 2016, which provided a more seamless and native user experience without the need for explicit VM management. Today, it primarily serves niche use cases for provisioning isolated Docker hosts or for managing specific legacy systems.


title: SYNOPSIS
content:
<b>docker network</b> <i>&lt;subcommand&gt;</i> [OPTIONS]<br><br><b>Common Subcommands:</b><br>&nbsp;&nbsp;<b>docker network connect</b> [OPTIONS] <i>NETWORK CONTAINER</i><br>&nbsp;&nbsp;<b>docker network create</b> [OPTIONS] <i>NETWORK</i><br>&nbsp;&nbsp;<b>docker network disconnect</b> [OPTIONS] <i>NETWORK CONTAINER</i><br>&nbsp;&nbsp;<b>docker network inspect</b> [OPTIONS] <i>NETWORK [NETWORK...]</i><br>&nbsp;&nbsp;<b>docker network ls</b> [OPTIONS]<br>&nbsp;&nbsp;<b>docker network prune</b> [OPTIONS]<br>&nbsp;&nbsp;<b>docker network rm</b> [OPTIONS] <i>NETWORK [NETWORK...]</i>


title: PARAMETERS
content:
<b><b>connect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect a container to a network.<br><br><b><b>create</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new network.<br><br><b><b>disconnect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disconnect a container from a network.<br><br><b><b>inspect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information on one or more networks.<br><br><b><b>ls</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List networks.<br><br><b><b>prune</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all unused networks.<br><br><b><b>rm</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove one or more networks.<br><br><b><i>NETWORK</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name or ID of the network.<br><br><b><i>CONTAINER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name or ID of the container.<br><br><b><b>-d</b>, <b>--driver</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Driver to use for the network (e.g., 'bridge', 'overlay'). <i>(create)</i><br><br><b><b>--attachable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable manual container attachment to the network. <i>(create)</i><br><br><b><b>--internal</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restrict external access to the network. <i>(create)</i><br><br><b><b>--subnet</b> <i>strings</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subnet in CIDR format for the network segment. <i>(create)</i><br><br><b><b>--gateway</b> <i>strings</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;IPv4 or IPv6 gateway for the master subnet. <i>(create)</i><br><br><b><b>--ip-range</b> <i>strings</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allocate container IP from a sub-range. <i>(create)</i><br><br><b><b>-o</b>, <b>--opt</b> <i>map</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set driver specific options. <i>(create)</i><br><br><b><b>--alias</b> <i>strings</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add network-scoped alias for the container. <i>(connect)</i><br><br><b><b>--ip</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Static IPv4 address for the container on this network. <i>(connect)</i><br><br><b><b>-f</b>, <b>--filter</b> <i>filter</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter output based on conditions provided. <i>(inspect, ls)</i><br><br><b><b>--format</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print networks using a Go template. <i>(inspect, ls)</i><br><br><b><b>--no-trunc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't truncate output. <i>(ls)</i><br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show network IDs. <i>(ls)</i><br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for confirmation when pruning. <i>(prune)</i><br><br>


title: DESCRIPTION
content:
The `docker network` command is a crucial tool for managing Docker container networks. It allows users to create, inspect, connect, disconnect, and remove networks, defining how containers communicate with each other and with the outside world. Docker provides several built-in network drivers (like <b>bridge</b>, <b>host</b>, <b>none</b>, <b>overlay</b>, and <b>macvlan</b>) and supports custom network plugins, enabling flexible network topologies. This command is fundamental for isolating applications, securing communication pathways, and building robust distributed systems with Docker. It manages the entire lifecycle of networks, from initial setup to cleanup.


title: CAVEATS
content:
Different network drivers (e.g., <b>bridge</b>, <b>overlay</b>, <b>macvlan</b>) have distinct capabilities and use cases. The <b>bridge</b> driver is suitable for single-host container communication, while <b>overlay</b> is essential for multi-host Docker Swarm clusters. Removing a network will disconnect all containers attached to it. Networks created with the <b>--internal</b> flag will restrict external access to their connected containers, enhancing security.


title: BUILT-IN NETWORK DRIVERS
content:
Docker provides several built-in network drivers:<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>bridge</b>: The default network driver. Containers on the same bridge network can communicate, and it provides NAT for external access.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>host</b>: Removes network isolation between the container and the Docker host. The container shares the host's network stack.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>none</b>: Disables all networking for the container.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>overlay</b>: Used for multi-host communication in Docker Swarm mode. Creates a distributed network segment across multiple Docker daemons.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>macvlan</b>: Allows assigning a MAC address to a container, making it appear as a physical device on your network. Useful for legacy applications.


title: DEFAULT NETWORKS
content:
By default, Docker creates three networks when installed:<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>bridge</b>: The default network for new containers if no other network is specified.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>host</b>: A special network mode that uses the host's network stack.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>none</b>: A special network mode that provides no networking for the container.


title: HISTORY
content:
Docker's networking capabilities have significantly evolved since its early days. Initially, basic host-only and linked container communication was prevalent. The introduction of <i>libnetwork</i> in Docker 1.9 (October 2015) revolutionized Docker networking by standardizing network drivers and providing a robust framework for pluggable network backends. This paved the way for advanced features like multi-host networking with the <b>overlay</b> driver, critical for Docker Swarm mode and distributed applications. This evolution aimed to provide more flexible, scalable, and secure networking solutions for containerized environments.


title: SYNOPSIS
content:
The command <i>docker-node</i> is not a standard Linux executable. It conceptually refers to the process of running Node.js applications within Docker containers. A typical usage pattern involves:<br><b>docker run [OPTIONS] [IMAGE_NAME] [NODE_APP_COMMAND]</b><br>or to build an image:<br><b>docker build [BUILD_OPTIONS] . -t [IMAGE_NAME]</b>


title: PARAMETERS
content:
<b><b>-p &lt;host_port&gt;:&lt;container_port&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maps a port from the container to the host machine, making the Node.js application accessible from the host. (Used with <b>docker run</b>)<br><br><b><b>-v &lt;host_path&gt;:&lt;container_path&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts a host directory as a volume in the container, commonly used for live code changes or persistent data. (Used with <b>docker run</b>)<br><br><b><b>-it</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allocates a pseudo-TTY and keeps STDIN open, allowing for interactive sessions with the container. (Used with <b>docker run</b>)<br><br><b><b>--rm</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically removes the container when it exits. (Used with <b>docker run</b>)<br><br><b><b>--name &lt;container_name&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a name to the container for easier identification. (Used with <b>docker run</b>)<br><br><b><b>--env &lt;key&gt;=&lt;value&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets environment variables inside the container, useful for configuration. (Used with <b>docker run</b>)<br><br><b><b>-t &lt;image_name&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Names and optionally tags the image in the 'name:tag' format. (Used with <b>docker build</b>)<br><br><b><b>[IMAGE_NAME]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name or ID of the Docker image containing the Node.js application to be run.<br><br><b><b>[NODE_APP_COMMAND]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The command to execute inside the container, typically <i>node app.js</i> or <i>npm start</i>.<br><br>


title: DESCRIPTION
content:
The term <i>docker-node</i> refers to the practice of leveraging Docker to build, run, and deploy Node.js applications. It's not a standalone command but rather a conceptual way to describe how Docker's containerization technology benefits Node.js development by providing isolated environments. This approach ensures dependency consistency, simplifies deployment across different environments (development, staging, production), and avoids 'works on my machine' issues. Users typically define a <i>Dockerfile</i> to specify how their Node.js application should be built into a Docker image, including installing Node.js, copying application code, installing npm dependencies, and defining the application's entry point. Once an image is built, it can be run as a container, providing a lightweight, portable, and self-sufficient runtime for the Node.js application.


title: CAVEATS
content:
The term <i>docker-node</i> is not a standalone executable command; it represents a conceptual workflow using Docker. Using Docker adds an abstraction layer and a learning curve. Initial setup can be complex, and debugging can sometimes be more challenging than with local execution. Performance overhead, though generally minimal, might be a consideration for very high-performance applications, and image size can grow large if not managed properly with techniques like multi-stage builds.


title: DOCKERFILE FOR NODE.JS
content:
A <i>Dockerfile</i> is a script of instructions used to build a Docker image. For Node.js, it typically includes:<br><i>FROM node:latest</i> (or a specific version)<br><i>WORKDIR /app</i> (sets the working directory within the container)<br><i>COPY package*.json ./</i> (copies manifest files to leverage Docker's build cache)<br><i>RUN npm install</i> (installs Node.js dependencies)<br><i>COPY . .</i> (copies the rest of the application code)<br><i>EXPOSE &lt;port&gt;</i> (informs Docker that the container listens on the specified network ports at runtime, e.g., 3000)<br><i>CMD ["node", "app.js"]</i> (defines the default command to execute when the container starts).


title: BEST PRACTICES
content:
Key best practices for containerizing Node.js applications include using small, official base images (e.g., <i>node:alpine</i>) to minimize image size. Implementing multi-stage builds is crucial to reduce the final image size by separating build-time dependencies (like compilers) from runtime dependencies. It's also vital to ensure applications run as a non-root user inside the container for security. Lastly, leverage <i>.dockerignore</i> to exclude unnecessary files (e.g., local <i>node_modules</i>, <i>.git</i>, <i>.env</i> files) from the build context, speeding up builds and reducing image size.


title: HISTORY
content:
Docker emerged in 2013, revolutionizing application deployment through containerization. For Node.js applications, Docker quickly became indispensable due to the complexities of managing <i>node_modules</i> and ensuring consistent runtime environments across development, testing, and production. Early adoption focused on simplifying dependency management and overcoming 'environment drift.' The evolution of Dockerfiles and best practices, such as multi-stage builds and smaller base images, has continuously optimized the process of containerizing Node.js applications, making it a standard practice in modern web development.


title: SYNOPSIS
content:
docker ps [OPTIONS]<br><i>Note: The command 'docker-ps' is not a standard Docker command; this analysis pertains to 'docker ps'.</i>


title: PARAMETERS
content:
<b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all containers, including those that are stopped or exited. By default, only running containers are shown.<br><br><b><b>-f</b>, <b>--filter</b> <i>FILTER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter output based on conditions provided, such as <i>status=exited</i>, <i>ancestor=ubuntu</i>, or <i>name=my-container</i>.<br><br><b><b>--format</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print containers using a Go template, allowing custom output formats. For example, <i>--format '{{.ID}}: {{.Names}}'</i>.<br><br><b><b>-n</b>, <b>--last</b> <i>int</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show <i>n</i> last created containers (includes all states: running, exited, etc.). The default is -1, meaning all containers when combined with <b>-a</b>.<br><br><b><b>--no-trunc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't truncate output, showing full container IDs and names instead of shortened versions.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only display numeric IDs of containers, useful for scripting or piping output to other commands.<br><br><b><b>-s</b>, <b>--size</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display total file sizes of the container and its writable layer.<br><br>


title: DESCRIPTION
content:
<i>docker ps</i> is a fundamental command within the Docker command-line interface (<i>CLI</i>) used to inspect and manage Docker containers. It provides a quick overview of containers that are currently running on your system, showing crucial details such as their <b>ID</b>, the <b>image</b> they are based on, the <b>command</b> executed inside them, when they were <b>created</b>, their current <b>status</b> (e.g., Up, Exited), <b>ports</b> they expose, and their <b>names</b>. By default, <i>docker ps</i> only displays active, running containers. However, with various options, it can be extended to show all containers, including those that have stopped or exited, filter results based on specific criteria, or format the output for easier parsing. This command is indispensable for developers and system administrators working with Docker, enabling them to quickly verify container health, identify running services, and prepare for further container management actions like stopping, starting, or removing containers.


title: CAVEATS
content:
<ul><li>By default, <i>docker ps</i> only lists <b>running</b> containers. Users often forget the <b>-a</b> or <b>--all</b> option when troubleshooting missing containers that are stopped.</li><li>The output can be quite wide, requiring a larger terminal window or the use of <b>--no-trunc</b> to see full details.</li><li>Filtering with <b>--filter</b> requires understanding of available filter keys (e.g., <i>status</i>, <i>name</i>, <i>id</i>, <i>label</i>) and their valid values.</li></ul>


title: UNDERSTANDING OUTPUT COLUMNS
content:
A typical <i>docker ps</i> output includes:<br><b>CONTAINER ID</b>: A unique identifier for the container.<br><b>IMAGE</b>: The Docker image used to create the container.<br><b>COMMAND</b>: The command executed when the container starts.<br><b>CREATED</b>: How long ago the container was created.<br><b>STATUS</b>: The current state of the container (e.g., Up X minutes, Exited Y seconds ago).<br><b>PORTS</b>: Port mappings between the host and the container.<br><b>NAMES</b>: The name assigned to the container (either automatically generated or user-defined).


title: HISTORY
content:
The <i>docker ps</i> command has been a core component of the Docker <i>CLI</i> since the early days of Docker's development, which began around 2013. As Docker revolutionized containerization, <i>docker ps</i> quickly became one of the most frequently used commands, essential for monitoring and managing the lifecycle of containers. Its syntax and core functionality have remained largely consistent, reflecting its fundamental role in providing immediate visibility into the state of containers running on a Docker host. Continuous development has focused on adding useful options like advanced filtering and formatting capabilities, enhancing its utility for more complex container orchestration scenarios.


title: SEE ALSO
content:
docker run(1), docker stop(1), docker start(1), docker rm(1), docker images(1), docker logs(1), ps(1)


title: PARAMETERS
content:
<b>--all-tags, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Downloads all tagged images for the repository. Instead of just one tag (e.g., 'latest'), it fetches every version available.<br><br><b>--disable-content-trust</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips image content trust verification. By default, Docker attempts to verify the integrity and publisher of an image using Notary. This flag bypasses that check.<br><br><b>--platform string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target platform if the image is multi-platform capable (e.g., <I>linux/amd64</I>, <I>linux/arm64</I>). This is crucial for pulling images designed for different CPU architectures.<br><br><b>--quiet, -q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses verbose output during the pull process, showing only error messages or essential information.<br><br>


title: DESCRIPTION
content:
The <b>docker pull</b> command is used to download Docker images from a configured registry, most commonly <I>Docker Hub</I> by default, or a private registry. <br><br>Docker images are read-only templates or blueprints that contain all the necessary components (application code, libraries, system tools, dependencies) to create a Docker container. When you execute <b>docker pull</b>, the command fetches all the required image layers for the specified image and tag (or digest) from the remote registry. These layers are then stored locally in Docker's image cache on your machine. <br><br>If no tag is specified for an image name, Docker automatically attempts to pull the <I>latest</I> tag. Once an image is pulled, it becomes available locally for use by other Docker commands, such as <b>docker run</b>, which creates and starts a container from the image. This command is fundamental for deploying pre-built applications or environments within the Docker ecosystem.


title: CAVEATS
content:
<ul><li><b>Network Requirement:</b> <b>docker pull</b> requires an active internet connection to reach remote registries.</li><li><b>Disk Space:</b> Pulled images consume local disk space, which can accumulate rapidly, especially with large or numerous images.</li><li><b>Content Trust:</b> While content trust is a security feature, it can sometimes cause issues if the image is not signed or if Notary services are unavailable. Using <b>--disable-content-trust</b> bypasses this security check.</li><li><b>Registry Access:</b> If pulling from a private registry, you must first authenticate using <b>docker login</b>.</li><li><b>Bandwidth Consumption:</b> Large images can consume significant network bandwidth, impacting download times and data usage.</li></ul>


title: IMAGE LAYERS AND EFFICIENCY
content:
Docker images are built up from a series of read-only layers. When you pull an image, Docker checks which layers you already have locally. It only downloads the new or updated layers, making the pull process highly efficient, especially for images that share common base layers (e.g., multiple Ubuntu-based images).


title: DOCKER REGISTRIES
content:
A Docker registry is a storage and distribution system for Docker images. Docker Hub is the default public registry, hosting millions of public and private images. Organizations can also set up private registries (e.g., Docker Trusted Registry, Harbor) to store their proprietary images securely. <b>docker pull</b> communicates directly with these registries to retrieve images.


title: HISTORY
content:
The <b>docker pull</b> command has been a cornerstone of the Docker CLI since its early days, shortly after Docker's initial public release around 2013. As Docker revolutionized containerization, the ability to easily fetch pre-built application images from a centralized repository (Docker Hub) became a fundamental workflow. Its development has focused on efficiency, leveraging Docker's layered filesystem to download only missing image layers, and security, with the introduction of content trust mechanisms. The command has evolved alongside Docker itself, adapting to new features like multi-platform images and improved registry interactions, maintaining its central role in the container lifecycle.


title: PARAMETERS
content:
<b><I>OLD_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The current <I>name</I> or <I>ID</I> of the Docker container you wish to rename.<br><br><b><I>NEW_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired new <I>name</I> for the container. This name must be unique among all containers.<br><br>


title: DESCRIPTION
content:
The <b>docker rename</b> command allows users to change the name of an already existing Docker container. This is particularly useful for organizing containers, adhering to naming conventions, or correcting misspellings without needing to stop, commit, remove, and recreate the container.<br><br>The command directly updates the container's metadata, making the change effective immediately. It does not require the container to be stopped; it can be running or stopped when renamed. This simplifies container management workflows significantly by providing a straightforward way to modify container identifiers.


title: CAVEATS
content:
The new name (<I>NEW_NAME</I>) must be unique among all existing containers. If a container with the <I>NEW_NAME</I> already exists, the command will fail.<br><br>If other containers are linked to the renamed container using the old name (via the deprecated `--link` flag), those links will become stale and will no longer resolve correctly.<br><br>For containers on user-defined networks, renaming <I>might</I> affect network aliases that were derived from the original name. However, the container's IP address and general network configuration typically remain unchanged.<br><br>Renaming does not affect the container's filesystem, installed applications, or running processes.


title: <I>IMPACT ON RUNNING CONTAINERS</I>
content:
The <b>docker rename</b> command can be used on both running and stopped containers. The rename operation is nearly instantaneous and does not interrupt the container's running processes or network connectivity. This allows for flexible naming changes without service disruption.


title: <I>NAME UNIQUENESS</I>
content:
Docker enforces unique names for all containers. If you attempt to rename a container to a name already in use by another container, the operation will fail with an error message indicating the name conflict. You must choose a name that is not currently assigned to any other container.


title: HISTORY
content:
The <b>docker rename</b> command was introduced in Docker Engine 1.10.0 (API version 1.22) on February 9, 2016. Before its introduction, renaming a container was not directly possible through the Docker CLI, requiring users to resort to complex workarounds like stopping, committing, removing the old container, and then running a new container with the desired name from the committed image. This feature significantly simplified container management and addressed a long-standing user request.


title: PARAMETERS
content:
<b>--force, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the removal of a running container. Docker will first stop the container before deleting it.<br><br><b>--volumes, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove any <i>anonymous</i> volumes associated with the container. This does <i>not</i> remove named volumes or host-mounted volumes.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for the <code>docker rm</code> command.<br><br>


title: DESCRIPTION
content:
The <code>docker rm</code> command is used to <b>delete one or more containers</b> from a Docker host. <br> <br> This command is fundamental for managing container lifecycle and freeing up system resources. When a container is removed, its writable layer is permanently deleted, and any resources it consumed, such as network interfaces and process IDs, are released. <br> <br> By default, <code>docker rm</code> can only remove <i>stopped</i> containers. Attempting to remove a running container without additional options will result in an error. To forcefully remove a running container, the <b><code>--force</code></b> (or <b><code>-f</code></b>) option must be used, which first attempts to stop the container before removing it. <br> <br> Users can specify containers by their ID or name. Multiple containers can be removed simultaneously by listing their IDs or names separated by spaces. It's crucial to understand that <code>docker rm</code> does not automatically remove data volumes (named volumes or host-mounted volumes) associated with the container; only <i>anonymous volumes</i> can be removed using the <b><code>--volumes</code></b> (or <b><code>-v</code></b>) option. This distinction helps prevent accidental data loss.


title: CAVEATS
content:
<b>Caveats and Limitations:</b><br><br><i>*   Removing a container with <code>docker rm</code> <b>permanently deletes its writable layer</b> and associated configurations.</i><br><i>*   By default, <code>docker rm</code> cannot remove a <i>running</i> container. The <b><code>--force</code></b> (<b><code>-f</code></b>) option is required to stop and then remove a running container.</i><br><i>*   The <b><code>--volumes</code></b> (<b><code>-v</code></b>) option only removes <i>anonymous</i> volumes. Named volumes or host-mounted volumes must be managed and removed separately using <code>docker volume rm</code>.</i><br><i>*   Ensure no critical data resides solely within the container's writable layer before removal, as it will be lost. Persistent data should always be stored in volumes.</i>


title: CLEANUP STRATEGY
content:
It's common practice to use <code>docker rm</code> in conjunction with <code>docker ps -aq</code> to remove all stopped containers: <br> <code>docker rm $(docker ps -aq)</code>. This command removes all containers that are not currently running.


title: EXIT STATUS
content:
The <code>docker rm</code> command typically exits with a status of <code>0</code> on success. A non-zero exit status indicates an error during the removal process.


title: HISTORY
content:
The <code>docker rm</code> command has been a core component of the Docker CLI since its early days, essential for managing the lifecycle of containers. Its functionality has remained largely consistent, reflecting its fundamental role in freeing up resources and cleaning the Docker environment. As Docker evolved, the emphasis shifted towards more robust volume management (named volumes vs. anonymous volumes) and network management, but the <code>rm</code> command's purpose of container deletion remained central.


title: SEE ALSO
content:
docker ps(1), docker stop(1), docker kill(1), docker rmi(1), docker volume rm(1), docker system prune(1)


title: PARAMETERS
content:
<b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Forces the removal of an image. This option can bypass checks, allowing the deletion of images even if they are used by stopped containers or are parents of other images. Use with caution as it can lead to orphaned containers or broken image dependencies.</i><br><br><b><b>--no-prune</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Prevents the deletion of untagged parent images. By default, `<b>docker rmi</b>` will remove untagged parent images (dangling images) if they are no longer referenced by any other image after the specified image is removed. This option disables that automatic pruning behavior.</i><br><br><b><i>IMAGE</i> [<i>IMAGE...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>One or more image names, IDs, or digests to be removed. You can specify multiple images by listing them space-separated.</i><br><br>


title: DESCRIPTION
content:
<i><br>The `<b>docker rmi</b>` command (short for remove image) is a fundamental part of the Docker CLI, used to delete one or more Docker images from the local image store. It's essential for managing disk space and keeping your Docker environment clean by removing old, unused, or unwanted image layers.<br><br>Images can be specified by their ID, name (e.g., `ubuntu:latest`), or digest. By default, `<b>docker rmi</b>` will prevent the removal of an image if it's currently referenced by a running container, or if it's a parent of another existing tagged image. This default behavior helps prevent accidental data loss or breaking dependencies.<br><br>For more aggressive cleanup, especially when an image is referenced by stopped containers or when dealing with complex image dependencies, options like `<b>--force</b>` can be used. It's crucial to understand the implications of removing images, as it can affect existing containers or break subsequent image builds if dependencies are not carefully managed.</i>


title: CAVEATS
content:
<i><br>An image cannot be removed if a container is currently <b>running</b> from it. You must stop and remove the container first (using `<b>docker stop</b>` and `<b>docker rm</b>`).<br><br>If an image is referenced by a <b>stopped</b> container, you will need to use the `<b>--force</b>` option to remove it. Be aware that this will leave the stopped container referencing a non-existent image.<br><br>Images that are parents of other tagged images cannot be removed unless the child images are removed first, or the `<b>--force</b>` option is used. Using `<b>--force</b>` in such cases can lead to child images that lack their foundational layers, potentially causing issues.<br><br>Be cautious with `<b>--force</b>` as it can lead to unexpected behavior, orphaned resources, or corrupted Docker environments if not used judiciously. Always ensure you understand the dependencies before forcing image removal.</i>


title: THE "DOCKER-RMI" MISCONCEPTION
content:
<i><br>The term "docker-rmi" is a common way users might conceptually refer to the command. However, in the Docker CLI, subcommands are always separated from the main `<b>docker</b>` command by a <b>space</b>, not a hyphen. Therefore, the correct and executable command is `<b>docker rmi</b>`. The hyphenated form is a common typo or a conceptual carry-over from other command-line interfaces where hyphens are used to separate commands (e.g., `git-add` sometimes refers to `git add`).</i>


title: DANGLING AND UNREFERENCED IMAGES
content:
<i><br><b>Dangling images</b> are image layers that have no relationship to any tagged images. They often occur when you build a new image and the previous layers become untagged but are still present on your system. While `<b>docker rmi</b>` can remove specific dangling images if you know their IDs, `<b>docker image prune</b>` is the more efficient and recommended command to clean up all dangling images or even all unreferenced images (those not used by any container and not having any tags).</i>


title: HISTORY
content:
<i><br>The `<b>docker rmi</b>` command has been a core component of the Docker CLI since its early versions, reflecting the fundamental need for users to manage their local image cache. Its functionality has remained largely consistent over time, emphasizing its role in cleaning up disk space and maintaining image hygiene.<br><br>As Docker matured, more sophisticated image management tools like `<b>docker image prune</b>` were introduced (starting with Docker 1.13, part of the new `<b>docker image</b>` subcommand structure) to complement `<b>rmi</b>` for automated and comprehensive cleanup of unused images, including dangling and unreferenced ones. While `<b>docker rmi</b>` is for explicit image removal, `<b>docker image prune</b>` offers a more automated approach to reclaim disk space.</i>


title: SEE ALSO
content:
docker images(1), docker image prune(1), docker pull(1), docker build(1), docker run(1), docker rm(1)


title: PARAMETERS
content:
<b>--detach / -d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run container in the background, printing new container ID.<br><br><b>--interactive / -i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep STDIN open even if not attached, useful for interactive processes.<br><br><b>--tty / -t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allocate a pseudo-TTY, often used with <b>-i</b> for interactive shell sessions.<br><br><b>--name <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign a specific name to the container, making it easier to reference.<br><br><b>--publish / -p <host_port>:<container_port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Publish a container's port(s) to the host, mapping specified ports.<br><br><b>--volume / -v <host_path>:<container_path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mount a file or directory from the host into the container for persistent storage.<br><br><b>--env / -e <key=value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set environment variables inside the container.<br><br><b>--rm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically remove the container when it exits, useful for temporary containers.<br><br><b>--network <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect the container to a specific Docker network (e.g., <i>host</i>, <i>bridge</i>, or custom).<br><br><b>--restart <policy></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the container's restart policy (e.g., <i>no</i>, <i>on-failure</i>, <i>always</i>, <i>unless-stopped</i>).<br><br><b>--entrypoint <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override the default ENTRYPOINT of the image.<br><br><b>--workdir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the working directory inside the container for the primary command.<br><br><b>--user <user>[:<group>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the command as a specified user or UID (and optional group) inside the container.<br><br><b>--hostname <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the container's hostname.<br><br>


title: DESCRIPTION
content:
The <b>docker run</b> command is fundamental to Docker, enabling users to create and start a new container from a specified <i>Docker image</i>. An image acts as a lightweight, standalone, executable package that includes everything needed to run a piece of software, including the code, a runtime, system tools, system libraries, and settings.<br><br>When <b>docker run</b> is executed, it provisions a new, isolated environment (the container) based on the image's blueprint. This container runs the command specified in the image or overridden by the user, providing process isolation and resource management. By default, containers are ephemeral, meaning any changes made inside them are lost once they stop, unless <i>volumes</i> are used for persistent storage.<br><br><b>docker run</b> is highly versatile, supporting a wide array of options to configure networking, expose ports, mount directories, set environment variables, limit resources, and define container lifecycle behavior, making it the primary tool for deploying and managing containerized applications.


title: CAVEATS
content:
<ul><li><b>Data Persistence</b>: By default, container data is lost when the container is removed. Use <b>--volume</b> to persist data outside the container's lifecycle, ensuring data survives container restarts or removals.</li><li><b>Security</b>: Running containers with <b>--privileged</b> or mounting sensitive host paths can introduce significant security risks. Always follow the principle of least privilege, granting only necessary permissions.</li><li><b>Resource Consumption</b>: Containers can consume significant host resources (CPU, memory, disk) if left unchecked. Use options like <b>--memory</b> and <b>--cpus</b> to limit resource usage and prevent host system performance degradation.</li><li><b>Image Specificity</b>: The behavior of <b>docker run</b> heavily depends on the <i>ENTRYPOINT</i> and <i>CMD</i> instructions defined within the Docker image. Understanding how these interact and how they can be overridden is crucial for predictable container execution.</li></ul>


title: NETWORKING CONCEPTS
content:
By default, containers connect to a <i>bridge network</i>, allowing communication with other containers on the same bridge and the host. Options like <b>--network</b> allow connecting to custom user-defined networks, running on the <i>host network</i> (sharing the host's network stack), or isolating the container entirely (<i>none network</i>) for specialized use cases. User-defined networks provide better isolation and name resolution for services.


title: ENTRYPOINT VS CMD
content:
In a Dockerfile, <i>ENTRYPOINT</i> defines the primary command that will execute when the container starts, acting as the executable. <i>CMD</i> provides default arguments to the <i>ENTRYPOINT</i> or an executable if no <i>ENTRYPOINT</i> is specified. <b>docker run</b> allows overriding both: the [COMMAND] argument passed directly to <b>docker run</b> overrides the image's <i>CMD</i>, while <b>--entrypoint</b> explicitly overrides the image's <i>ENTRYPOINT</i> itself.


title: IMAGE PULL POLICY
content:
When you execute <b>docker run</b>, Docker first checks if the specified image is available locally. If not, it attempts to pull it from a configured registry (like Docker Hub). The <b>--pull</b> option (with policies like <i>always</i>, <i>missing</i>, or <i>never</i>) allows explicit control over this behavior, ensuring you always use the latest image, only pull if missing, or avoid network requests entirely for local-only images.


title: HISTORY
content:
Docker emerged around 2013, quickly revolutionizing application deployment and portability. The <b>docker run</b> command has been central to this revolution from its inception, providing the core functionality for executing containerized applications. Its development has mirrored the evolution of Docker itself, incorporating new features like advanced networking, volume management, and resource controls, continually enhancing its capabilities to meet the demands of modern cloud-native architectures and microservices. It remains the most frequently used command for direct container interaction, serving as the gateway to containerized environments.


title: SEE ALSO
content:
<b>docker build(1)</b>: Build an image from a Dockerfile., <b>docker ps(1)</b>: List running containers., <b>docker stop(1)</b>: Stop one or more running containers gracefully., <b>docker rm(1)</b>: Remove one or more containers., <b>docker images(1)</b>: List Docker images stored locally., <b>docker exec(1)</b>: Run a command in a running container (e.g., to debug or inspect)., <b>docker compose(1)</b>: Define and run multi-container Docker applications using a YAML file.


title: PARAMETERS
content:
<b><b>--output</b>, <b>-o</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the saved image archive to a specified file path, instead of STDOUT. This option is convenient for directing the output directly to a file.<br><br>


title: DESCRIPTION
content:
<i>docker save</i> is a fundamental command in Docker for packaging one or more Docker images into a single tar archive. This archive contains all the layers, metadata, and tags associated with the specified images, preserving their history and integrity.<br><br>Unlike <i>docker export</i>, which flattens a running container's filesystem into a tarball and loses image layers and metadata, <i>docker save</i> specifically targets images, making it ideal for scenarios where images need to be transferred between Docker daemons without relying on a Docker registry. This includes offline transfers, air-gapped environments, creating backups of images, or moving images to development/testing environments that might not have direct access to public or private registries.<br><br>The resulting tar archive can then be easily loaded onto another Docker host using the <i>docker load</i> command, making the images available for use. The command can output the archive to standard output, which can then be redirected to a file, or directly to a specified file using the <b>--output</b> option. It supports saving multiple images into a single archive, consolidating them for easier management and transfer.


title: CAVEATS
content:
The saved archive can be very large, especially for images with many layers or large base images.<br>It saves <b>images</b>, not <b>containers</b>. To save a container's filesystem, use <i>docker export</i>.<br>The saved images do not include volumes or bind mounts unless they are part of the image's filesystem itself.


title: OUTPUT DESTINATION
content:
By default, <i>docker save</i> writes the tar archive to standard output (STDOUT). This allows for flexible redirection, for example, piping the output directly to a file using `>` or to another command. Alternatively, the <b>--output</b> (or <b>-o</b>) option can be used to specify a direct file path for the archive, which is generally more convenient for single-file operations.


title: MULTI-IMAGE SAVING
content:
The command supports saving multiple images into a single tar archive by listing them as arguments. For example, <i>docker save -o all_my_images.tar image1:tag image2:tag image3</i> will bundle all specified images into one archive, simplifying transfer and management.


title: HISTORY
content:
The <i>docker save</i> command has been a core utility in Docker since its early versions, providing a crucial mechanism for image portability outside of registry-based workflows. Its design reflects the need for offline distribution and migration of Docker images, which is essential for various enterprise and air-gapped environment deployments. It has remained largely stable in its functionality, focusing on its primary role of archiving images for transfer.


title: SYNOPSIS
content:
<b>docker-secret</b> <I>ACTION</I> [<i>SECRET_NAME</i>] [<i>OPTIONS</i>]<br><br>Examples of common actions and their hypothetical usage:<br>  <b>docker-secret create</b> <i>my_secret</i> <b>--file</b> <i>./secret.txt</i><br>  <b>docker-secret create</b> <i>db_password</i> <b>--value</b> <i>"secure_password"</i><br>  <b>docker-secret ls</b><br>  <b>docker-secret rm</b> <i>my_secret</i>


title: PARAMETERS
content:
<b><I>ACTION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The operation to perform. Common actions include <b>create</b> (to add a new secret), <b>remove</b> or <b>rm</b> (to delete a secret), <b>list</b> or <b>ls</b> (to view existing secrets), and potentially <b>get</b> or <b>inspect</b> (to retrieve or view details of a secret).<br><br><b><I>SECRET_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the Docker secret to create, remove, or inspect. This name is used by Docker services to access the secret.<br><br><b><b>--file</b> <I>&lt;path&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file from which to read the secret content. This is common for creating secrets from existing configuration files or sensitive data.<br><br><b><b>--value</b> <I>&lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the secret content directly as a string argument. Useful for small, inline secrets or programmatically generated values.<br><br><b><b>--label</b> <I>&lt;key=value&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds metadata labels to the secret, similar to Docker's native labeling capabilities. These labels can be used for organization or filtering.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces an action, such as the removal of a secret, without requiring confirmation.<br><br>


title: DESCRIPTION
content:
<b>docker-secret</b> typically refers to a <I>custom script</I> or a <I>utility</I> designed to simplify and automate the creation, management, and consumption of Docker secrets.<br><br>It is important to note that <b>docker-secret</b> is <I>not</I> a standard, officially distributed command included in the Docker CLI suite. Instead, it represents a common pattern or a third-party tool developed by the community to bridge gaps in existing Docker workflows, especially for local development with <b>docker-compose</b>, or for automating secret provisioning in CI/CD pipelines.<br><br>While Docker provides native commands like <b>docker secret create</b> and <b>docker secret ls</b> for managing secrets within a Swarm environment, a <b>docker-secret</b> utility often aims to provide a more convenient wrapper. It might automate tasks such as generating secrets from environment variables or files, making them easily consumable by Docker services, or integrating with `.env` files to provision secrets for local development stacks.


title: CAVEATS
content:
<b>docker-secret</b> is <I>not</I> a standard Docker command; its availability and specific functionality depend entirely on whether a custom script or third-party utility with this name has been installed or created on the system.<br><br>Its behavior can vary widely between different implementations. Users should always verify the source and functionality of any `docker-secret` script before use, especially concerning sensitive data.<br><br>For official Docker secret management, refer to the `docker secret` subcommands, which require Docker Swarm mode to be enabled.


title: COMMON USE CASES
content:
<ul><li><I>Local Development with docker-compose</I>: Automating the provisioning of secrets from local files (e.g., `.env` files) into Docker secrets, making them accessible to services defined in `docker-compose.yml` without manual intervention.</li><li><I>Secret Generation</I>: Generating strong, random passwords or API keys and injecting them as Docker secrets.</li><li><I>Automated Deployment</I>: Integrating secret creation and management into CI/CD pipelines to ensure sensitive data is securely handled during application deployment.</li></ul>


title: SECURITY CONSIDERATIONS
content:
When using any `docker-secret` utility, it's crucial to understand how it handles sensitive data. Ensure that secrets are not exposed in logs, environment variables, or version control. Always use secure methods for storing and transmitting secrets, and verify the integrity of the utility itself.


title: HISTORY
content:
The need for `docker-secret`-like utilities arose as Docker's native secret management (introduced with Docker Swarm) was initially focused on Swarm mode, leaving a gap for simpler, more direct secret handling in single-host deployments or during local development with `docker-compose`. Developers often created their own scripts to automate the creation of secrets from `.env` files or local paths, leading to the conceptual emergence of a 'docker-secret' utility that wraps or complements the official Docker CLI commands for ease of use in specific workflows.


title: SYNOPSIS
content:
<b>docker service</b> [OPTIONS] COMMAND<br><br>Available Commands:<br>&nbsp;&nbsp;create&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create a new service<br>&nbsp;&nbsp;inspect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Display detailed information on one or more services<br>&nbsp;&nbsp;logs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fetch the logs of a service or task<br>&nbsp;&nbsp;ls&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List services<br>&nbsp;&nbsp;ps&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List the tasks of one or more services<br>&nbsp;&nbsp;rm&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Remove one or more services<br>&nbsp;&nbsp;rollback&nbsp;&nbsp;&nbsp;&nbsp;Rollback changes to a service's configuration<br>&nbsp;&nbsp;scale&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Scale one or multiple replicated services<br>&nbsp;&nbsp;update&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Update a service<br><br>Run `<b>docker service</b> COMMAND <i>--help</i>` for more information on a specific subcommand.


title: PARAMETERS
content:
<b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the `<b>docker service</b>` command or its subcommands (e.g., `<b>docker service create</b> <i>--help</i>`).<br><br><b><i>-D</i>, <i>--debug</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug mode. Provides more verbose output for troubleshooting. This is a global Docker option that can precede `service`.<br><br><b><i>-H</i>, <i>--host</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Daemon socket(s) to connect to. Specifies the Docker daemon to communicate with. This is a global Docker option.<br><br><b><i>-v</i>, <i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the Docker version information and exit. This is a global Docker option.<br><br><b><i>[SUBCOMMAND OPTIONS]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Each `<b>docker service</b>` subcommand (e.g., `create`, `update`, `scale`) has its own extensive set of specific options. Refer to `<b>docker service</b> COMMAND <i>--help</i>` for details on each subcommand's parameters.<br><br>


title: DESCRIPTION
content:
The `<b>docker service</b>` command is a core component of Docker Swarm Mode, enabling the management of applications as distributed services across a cluster of Docker engines. It allows users to define desired states for applications, including the number of replicas, attached networks, exposed ports, and mount volumes. Docker Swarm then ensures that the service maintains this desired state, handling task scheduling, load balancing, and self-healing in case of node failures.<br><br>Services are the fundamental building blocks for orchestrating fault-tolerant, scalable, and highly available applications in a Swarm cluster. This command provides subcommands for creating, listing, inspecting, updating, scaling, and removing services, making it central to deploying and operating containerized applications in a production environment.


title: CAVEATS
content:
`<b>docker service</b>` commands are only available when Docker is running in <B>Swarm Mode</B>. If Swarm Mode is not initialized or joined on the Docker daemon, these commands will fail with an error. Managing stateful applications (e.g., databases) in Docker Swarm requires careful consideration of data persistence and distributed storage solutions, as services themselves are inherently stateless. While services abstract away individual containers (tasks), troubleshooting often requires inspecting individual tasks and their logs. The <B>overlay network</B> must be properly configured for services to communicate across different nodes in the Swarm.


title: SERVICE TYPES
content:
Docker services can be deployed as <B>replicated</B> services, where a specified number of identical tasks are run across the Swarm, or as <B>global</B> services, where one task is run on every available node in the Swarm. Replicated services are ideal for scaling applications, while global services are often used for monitoring agents or logging collectors.


title: ROLLING UPDATES
content:
The `<b>docker service update</b>` command supports rolling updates, allowing you to deploy new versions of a service without downtime. You can configure update parameters like parallelism (how many tasks to update concurrently), delay between updates, and rollback conditions, ensuring a smooth transition for your applications.


title: LOAD BALANCING
content:
Docker Swarm provides built-in <B>DNS-based load balancing</B> for services. When a service is created, Swarm assigns it a virtual IP (VIP) and DNS entry. Requests to the service name are load-balanced across all healthy tasks of that service, distributing traffic automatically.


title: HISTORY
content:
Docker Swarm Mode, including the `<b>docker service</b>` command, was introduced with Docker Engine 1.12 in June 2016. This release marked a significant shift by integrating native orchestration capabilities directly into the Docker CLI, making it much easier for users to set up and manage container clusters without external tools. Prior to this, Docker had a standalone `Docker Swarm` project, which was separate and less integrated. The integrated Swarm Mode aimed to provide a simpler, more opinionated orchestration solution compared to Kubernetes, focusing on ease of use for smaller to medium-sized deployments and immediate integration with the Docker ecosystem. Subsequent releases have introduced further enhancements to service capabilities, such as secret management, configuration management, and improved rolling updates.


title: SYNOPSIS
content:
<b>docker-slim</b> <i>&lt;command&gt;</i> [options] <i>&lt;image_name&gt;</i><br>Example: <b>docker-slim build --http-probe myapp:latest</b>


title: PARAMETERS
content:
<b><b>build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The primary command to <b>optimize</b> a Docker image, producing a smaller version.<br><br><b><b>xray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Analyzes a Docker image to show its contents and dependencies <i>without</i> slimming.<br><br><b><b>-t</b>, <b>--tag</b> <i>&lt;new_tag&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the tag for the <b>new, optimized</b> Docker image.<br><br><b><b>--http-probe</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables HTTP probing during analysis, ideal for web applications to <i>discover</i> dependencies.<br><br><b><b>--exec</b> <i>&lt;command&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a specific command inside the container to <i>profile</i> its runtime behavior.<br><br><b><b>--include-path</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the <b>inclusion</b> of a specified file or directory path into the final image.<br><br><b><b>--exclude-path</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the <b>exclusion</b> of a specified file or directory path from the final image.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs analysis and displays the optimization plan <i>without</i> building the new image.<br><br><b><b>--pull</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pulls the target Docker image from the registry if not available locally.<br><br><b><b>--from-dockerfile</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a Dockerfile path to build the <i>base image</i> before slimming.<br><br>


title: DESCRIPTION
content:
<b>docker-slim</b> is an open-source command-line utility designed to <i>automatically reduce</i> the size of Docker images without altering the application's code or behavior. It achieves this by performing a multi-stage analysis:<br>First, it runs the original container, <i>monitors its activity</i> (such as file system access, network connections, and executed commands), and identifies all dynamically linked libraries and other dependencies used by the application during runtime. After this comprehensive analysis, it constructs a new, <i>optimized Docker image</i> that contains only the essential components discovered during the profiling phase.<br>This process dramatically reduces the image's <b>attack surface</b>, improves startup times, and minimizes resource consumption, leading to more efficient and secure deployments. It is versatile, working across various programming languages and frameworks by observing the actual runtime footprint rather than relying on static analysis or language-specific package managers.


title: CAVEATS
content:
<b>docker-slim</b> relies on <i>runtime profiling</i>, meaning if an application path is not executed during profiling (e.g., a rarely used error handler), its dependencies might be removed.<br>It requires a running Docker daemon and <i>root privileges</i> to function correctly.<br>Complex applications or those with dynamic library loading might require careful configuration of <b>--exec</b> or <b>--include-path</b> to ensure all necessary components are retained.<br>It's generally <i>less effective</i> on already minimal base images like 'scratch' or 'distroless'.


title: <B>HOW IT WORKS: RUNTIME ANALYSIS</B>
content:
<b>docker-slim</b> operates by <i>monitoring</i> the target container's behavior during its execution. It observes file system access, network connections, and executed processes to determine precisely which files and libraries are <b>actively used</b> by the application. This dynamic analysis allows it to create a highly optimized image containing only the essential components, unlike static analysis which can miss dynamic dependencies.


title: <B>BENEFITS OF SLIMMING</B>
content:
Reducing Docker image size offers multiple benefits: <br><b>Enhanced Security:</b> A smaller attack surface due to fewer unnecessary components.<br><b>Improved Performance:</b> Faster image pulls, reduced startup times, and lower resource consumption.<br><b>Cost Savings:</b> Less storage required and reduced data transfer costs, especially in cloud environments.


title: HISTORY
content:
<b>docker-slim</b> was created by <b>Dmitry Fillin</b> and first released around <i>2017-2018</i>. Its development was driven by the common challenge of 'fat' Docker images, which often contain numerous unnecessary files and libraries, increasing their attack surface and deployment overhead. By providing an automated solution for image optimization, it quickly gained traction within the containerization community. It remains an <i>active open-source project</i>, continuously updated to support new Docker features and runtime environments.


title: PARAMETERS
content:
<b>-a, --attach</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach STDOUT/STDERR and forward signals to the container. This allows you to see the container's output in your terminal and interact with it if it accepts input.<br><br><b>-i, --interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach container's STDIN. This is commonly used in conjunction with <b>-a</b> to allow interactive input to the container, such as when starting a shell or a command that requires user interaction.<br><br><b>--detach-keys string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override the default key sequence for detaching a container (e.g., 'ctrl-p,ctrl-q'). This is useful when <b>-a</b> or <b>-i</b> is used and you need to detach without stopping the container.<br><br>


title: DESCRIPTION
content:
The <b>docker start</b> command is a fundamental tool used to resume the execution of one or more previously stopped Docker containers. Unlike <b>docker run</b>, which is used to create and then start a <i>new</i> container from a Docker image, <b>docker start</b> operates solely on existing containers. When invoked, it brings a container that is in a 'stopped' state back into a 'running' state, leveraging its existing filesystem, configuration (such as port mappings, volume mounts, and environment variables), and network settings. This command is crucial for managing container lifecycles, enabling users to pause and resume work with persistent environments without the overhead of re-creating a container from scratch. It is particularly useful for long-running services or development environments that need to be brought online or offline efficiently.


title: CAVEATS
content:
<i><b>Important Considerations:</b></i><br><i>The specified CONTAINER must exist and be in a stopped state for <b>docker start</b> to be effective.</i><br><br><i><b>docker start</b> does not re-create or modify the container's original configuration (e.g., port mappings, volume mounts, environment variables); these are preserved from its initial creation with <b>docker run</b>.</i><br><br><i>If the container was configured with a restart policy during <b>docker run</b>, <b>docker start</b> will respect that policy if the container stops unexpectedly after being started.</i>


title: CONTAINER IDS AND NAMES
content:
You can specify containers by their full ID, short ID, or name. For example, <b>docker start my-container-name</b> or <b>docker start a1b2c3d4e5f6</b>.


title: STARTING MULTIPLE CONTAINERS
content:
You can start multiple containers at once by listing their IDs or names separated by spaces, like <b>docker start container1 container2 container3</b>.


title: HISTORY
content:
The <b>docker start</b> command has been a fundamental part of the Docker CLI since the early days of Docker's public release in 2013. As Docker matured from a lightweight virtualization solution to a full-fledged containerization platform, the ability to manage the lifecycle of containers – including starting, stopping, and restarting them – became crucial. <b>docker start</b> specifically addresses the need to resume work on a persistent container environment, contrasting with <b>docker run</b> which focuses on initial container creation. Its core functionality has remained consistent, reflecting its foundational role in container orchestration.


title: SYNOPSIS
content:
<i><b>docker stats [OPTIONS] [CONTAINER...]</b></i><br><br>This command is a subcommand of the main <i><b>docker</b></i> CLI. It accepts various <i><b>OPTIONS</b></i> to modify its behavior and can target specific <i><b>CONTAINER</b></i> names or IDs. If no containers are specified, it defaults to showing statistics for all running containers.


title: PARAMETERS
content:
<b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all containers (default shows only running containers).<br><br><b><b>--no-stream</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable streaming stats and only pull the first result, providing a single snapshot of resource usage.<br><br><b><b>--format</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print stats using a Go template. For example, <i>--format "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}"</i>.<br><br><b><b>--no-trunc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not truncate output. Useful for displaying full container IDs or names.<br><br>


title: DESCRIPTION
content:
The <i><b>docker stats</b></i> command provides a <i><b>live stream of resource usage statistics</b></i> for one or more Docker containers. By default, it displays metrics for running containers, including <i><b>CPU percentage</b></i>, <i><b>memory usage</b></i> (with limit), <i><b>network I/O</b></i> (input/output), <i><b>block I/O</b></i> (disk reads/writes), and <i><b>process IDs (PIDs)</b></i>. This command is invaluable for <i><b>monitoring container performance</b></i>, identifying resource bottlenecks, and debugging issues in a Dockerized environment. When invoked without specific container names or IDs, it shows statistics for all currently running containers. The stream continues until manually interrupted (e.g., Ctrl+C) or if the <i><b>--no-stream</b></i> option is used to capture a single snapshot. It offers quick, at-a-glance insights into your containerized applications' resource consumption.


title: CAVEATS
content:
<i><b>docker stats</b></i> relies on the Docker daemon for metrics, which means it <i><b>requires the Docker daemon to be running and accessible</b></i>. The CPU percentage shown can sometimes be misleading as it's calculated based on the host's total CPU cores, not necessarily the container's allocated shares or limits. Memory usage represents the total memory consumed by the container, which includes filesystem cache and other kernel-level allocations, not just application-specific memory. For very high-resolution or historical data, other tools like Prometheus and Grafana, integrated with Docker, might be more suitable. There can be a slight overhead involved in collecting and streaming these statistics, especially with a large number of containers.


title: OUTPUT FIELDS EXPLAINED
content:
The default output of <i><b>docker stats</b></i> includes several columns:<br><ul><li><b>CONTAINER ID</b>: The unique ID of the container.</li><li><b>NAME</b>: The name of the container.</li><li><b>CPU %</b>: The current CPU usage percentage of the container.</li><li><b>MEM USAGE / LIMIT</b>: Current memory usage and the total memory limit for the container.</li><li><b>NET I/O</b>: Network input/output, showing bytes sent and received.</li><li><b>BLOCK I/O</b>: Block input/output, showing bytes read from and written to block devices.</li><li><b>PIDS</b>: The number of processes currently running inside the container.</li></ul>


title: CUSTOM FORMATTING WITH --FORMAT
content:
The <i><b>--format</b></i> option allows for highly customizable output using Go templates. This is particularly useful for scripting or integrating <i><b>docker stats</b></i> output into other tools. Available placeholders include <i><b>.ID</b></i>, <i><b>.Name</b></i>, <i><b>.CPUPerc</b></i>, <i><b>.MemUsage</b></i>, <i><b>.MemLimit</b></i>, <i><b>.MemPerc</b></i>, <i><b>.NetIO</b></i>, <i><b>.BlockIO</b></i>, <i><b>.PIDs</b></i>. For example, to get just the container ID and CPU percentage in a table format: <i><b>docker stats --format "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}"</b></i>.


title: HISTORY
content:
The <i><b>docker stats</b></i> command was introduced relatively early in Docker's development lifecycle, becoming a staple for users needing immediate insight into container resource consumption. Its inclusion underscored Docker's commitment to providing robust monitoring capabilities directly within its command-line interface. Over time, features like the <i><b>--format</b></i> option were added to enhance its utility, allowing users to customize output for scripting and integration purposes. It has consistently remained a core component of the <i><b>docker</b></i> CLI, evolving with the Docker engine itself to provide more accurate and comprehensive metrics.


title: PARAMETERS
content:
<b><i>SOURCE_IMAGE[:TAG]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name or ID of the existing image you wish to tag. Optionally, you can specify an existing tag for that image after a colon (e.g., <i>ubuntu:18.04</i>). If no tag is provided for the source, Docker will implicitly use <i>:latest</i>.<br><br><b><i>TARGET_IMAGE[:TAG]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The new name (repository) and optionally a new tag you want to assign to the source image. The repository name can include a registry host (e.g., <i>myregistry.com/my-app</i>). If no tag is provided for the target, Docker will implicitly use <i>:latest</i> for the new tag.<br><br>


title: DESCRIPTION
content:
The <b>docker tag</b> command creates an <i>additional tag</i> (or alias) for an existing Docker image. It does not create a new image nor does it duplicate any image layers. Instead, it simply creates a new pointer, or a new reference, to an existing image's unique identifier (ID).<br><br>This command is crucial for managing different versions of an image, or for preparing an image to be pushed to a specific Docker registry. For instance, you might build an image and initially tag it as <i>my-app:dev</i>. Once testing is complete, you can use <b>docker tag</b> to add another tag like <i>my-app:v1.0</i> or <i>myregistry.com/my-app:prod</i> to the exact same image ID. This allows the same underlying image to be referenced by multiple names, making it easier to organize, deploy, and manage different stages or environments of your application.<br><br>While <b>docker build -t</b> can tag an image during its creation, <b>docker tag</b> is used to apply additional tags to an image that already exists on your local Docker daemon. It's a lightweight operation, as it only modifies metadata within the Docker image store, having no impact on disk space beyond the small amount needed for the tag itself.


title: CAVEATS
content:
The <b>docker tag</b> command only creates a local reference. To make the new tag available to others or on different machines, you must use <b>docker push</b> to upload the image with its new tag to a Docker registry.<br><br>If the <i>TARGET_IMAGE[:TAG]</i> already exists, <b>docker tag</b> will overwrite that existing tag, effectively pointing it to the <i>SOURCE_IMAGE</i>. This might cause the image previously pointed to by <i>TARGET_IMAGE[:TAG]</i> to become 'dangling' (untagged) if it has no other tags.


title: DEFAULT TAG BEHAVIOR
content:
When you omit the <i>:TAG</i> part for the <i>TARGET_IMAGE</i>, Docker automatically assigns the tag <i>:latest</i> to the new reference. This means that <i>docker tag myimage mynewimage</i> is equivalent to <i>docker tag myimage:latest mynewimage:latest</i> (assuming <i>myimage</i> implicitly uses <i>:latest</i> as well).


title: OVERWRITING EXISTING TAGS
content:
Be cautious when tagging an image with a <i>TARGET_IMAGE[:TAG]</i> that already exists. The old image that was associated with that <i>TARGET_IMAGE[:TAG]</i> will no longer be referenced by it. If that old image has no other tags, it will become an untagged (dangling) image, which can then be cleaned up using <i>docker image prune</i>.


title: HISTORY
content:
The <b>docker tag</b> command has been a fundamental part of Docker's command-line interface since its early days. Its core functionality, enabling users to create aliases or version indicators for their Docker images, has remained consistent and is indispensable for image lifecycle management, especially when integrating with continuous integration/continuous deployment (CI/CD) pipelines and public or private registries.


title: PARAMETERS
content:
<b>CONTAINER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>name</b> or <b>ID</b> of the running container whose processes you want to display.<br>This parameter is <i>mandatory</i>.<br><br><b>ps OPTIONS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Additional options that are passed directly to the <i>ps</i> command executed within the container.<br>These options allow you to customize the output format and content, just as you would with the standard Linux <i>ps</i> command (e.g., <i>aux</i>, <i>-ef</i>, <i>-o pid,comm,args</i>).<br><br>


title: DESCRIPTION
content:
The <b>docker top</b> command provides a powerful way to inspect the processes actively running within a specified Docker container. It functions similarly to the <i>ps</i> command on a traditional Linux host, but its scope is limited to the isolated environment of a single container. <br><br>When invoked, <b>docker top</b> queries the container's process namespace and reports details such as the process ID (<i>PID</i>), user (<i>USER</i>), CPU usage (<i>%CPU</i>), memory usage (<i>%MEM</i>), start time (<i>START</i>), and the full command (<i>COMMAND</i>) being executed. <br><br>This command is invaluable for debugging, understanding the runtime behavior of applications within containers, and verifying that expected processes are indeed active. Unlike the host's <i>top</i> command, <b>docker top</b> provides a static snapshot of processes at the time of invocation rather than a continuously updating view. For <b>docker top</b> to function, the target container must be in a <b>running</b> state, and typically, the <i>ps</i> utility must be available within the container's filesystem for Docker to execute it internally.


title: CAVEATS
content:
The target container must be in a <b>running</b> state for <b>docker top</b> to retrieve process information.<br>The <i>ps</i> utility must be present and executable <i>inside</i> the container's filesystem for this command to work effectively. Minimal base images might sometimes lack this utility.<br>The PIDs displayed are those <i>within the container's isolated PID namespace</i>, not the PIDs on the host system.<br><b>docker top</b> provides a <i>snapshot</i> of processes at a given moment; it does not offer a continuous, real-time update like the host's <i>top</i> command. For real-time resource monitoring, consider <i>docker stats</i>.


title: DEFAULT OUTPUT COLUMNS
content:
By default, <b>docker top</b> typically displays columns similar to <i>ps -ef</i> or <i>ps aux</i>, including <b>UID</b> (User ID), <b>PID</b> (Process ID within the container), <b>PPID</b> (Parent Process ID), <b>C</b> (CPU utilization), <b>STIME</b> (Start Time), <b>TTY</b> (Controlling Terminal), <b>TIME</b> (Cumulative CPU time), and <b>CMD</b> (Command executed).


title: CUSTOMIZING OUTPUT WITH PS OPTIONS
content:
You can pass standard <i>ps</i> options to <b>docker top</b> to tailor the output. For example, <i>docker top my_container aux</i> will show all processes belonging to all users with user-oriented output, while <i>docker top my_container -o pid,comm,args</i> will display only the PID, command name, and full arguments list. This flexibility is crucial for precise debugging.


title: HISTORY
content:
The <b>docker top</b> command has been a fundamental part of the Docker CLI since its early versions, reflecting the core need to inspect the contents and behavior of running containers. It was designed to offer a familiar <i>ps</i>-like interface for containerized processes, fitting seamlessly into the Docker ecosystem's approach to container management and debugging. Its functionality has remained largely consistent, adapting as Docker's underlying container technology evolved.


title: SYNOPSIS
content:
As <b>docker-update</b> is not a standard Docker CLI command, there is no fixed, universal synopsis. Its invocation depends entirely on how the custom script is implemented. However, a conceptual synopsis for such a script, often placed in the system's PATH, might resemble:<br><b>docker-update</b> [<i>OPTIONS</i>] [<i>CONTAINER_NAMES</i>...]<br>or<br><b>docker-update</b> [<i>ACTION</i>]


title: PARAMETERS
content:
<b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Conceptual)</i> To update all known containers managed by the script.<br><br><b>-c <name>, --container <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Conceptual)</i> To specify a particular container or list of containers to update.<br><br><b>-i <image>, --image <image></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Conceptual)</i> To pull and update based on a specific image name or tag.<br><br><b>--no-recreate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Conceptual)</i> To only pull new images without stopping/restarting containers.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Conceptual)</i> To show what would be updated without performing any actual changes.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Conceptual)</i> To display script-specific help information.<br><br>


title: DESCRIPTION
content:
The command <b>docker-update</b> is <I>not</I> a native or standard command provided by the Docker CLI. Instead, it typically refers to a custom shell script or automation tool created by users or system administrators to simplify the process of updating Docker images and recreating or updating running containers. The primary purpose of such a script is to automate the manual steps involved in deploying new versions of containerized applications.<br><br>This often includes:<br><ul><li>Pulling the latest versions of Docker images from registries.</li><li>Stopping existing containers that use older images.</li><li>Removing stopped containers.</li><li>Creating and starting new containers using the freshly pulled images, often ensuring data persistence via volumes.</li><li>Optionally, handling cleanup of old, unused images.</ul><br>Because <b>docker-update</b> is user-defined, its exact behavior, options, and parameters vary greatly depending on its implementation. It serves as a common conceptual name for the automated maintenance of Docker environments, bridging the gap for a full "update everything" command that Docker's native CLI does not provide out-of-the-box for all scenarios.


title: CAVEATS
content:
<ul><li><b>Not a Standard Command:</b> The most significant caveat is that <b>docker-update</b> is not part of the official Docker CLI. Its existence and functionality depend entirely on a user-defined script.</li><li><b>Variability:</b> Behavior, options, and robustness differ vastly between implementations. A script found online may not work as expected or could contain errors.</li><li><b>Security Risks:</b> Running arbitrary <b>docker-update</b> scripts from unknown sources can pose significant security risks, as they often require elevated permissions to interact with the Docker daemon and could execute malicious commands.</li><li><b>Dependency Management:</b> Custom scripts require maintenance. Changes in Docker's underlying commands or APIs might break older scripts.</li><li><b>Error Handling:</b> Robust error handling is often lacking in simple custom scripts, potentially leaving containers in an inconsistent state if an update fails midway.</li></ul>


title: COMMON SCRIPTING PATTERNS
content:
A typical <b>docker-update</b> script often involves iterating through a list of container names or Docker Compose project directories. For each, it would attempt to pull the latest image, then gracefully stop and remove the old container, and finally re-launch a new container with the updated image, ensuring proper volume mounts and network configurations are preserved. Some more advanced scripts might include rollback capabilities or health checks after restarting. Users often place these scripts in a directory included in their system's PATH, such as <code>/usr/local/bin</code> or <code>~/bin</code>, and ensure they are executable.


title: HISTORY
content:
The concept behind a "docker-update" command emerged from the need for convenient, one-shot automation in managing Docker deployments. While Docker provides granular commands for each step (pull, stop, rm, run), there was no single, high-level command to orchestrate the entire image-update-container-recreation lifecycle for individual containers or small groups. This led many users and system administrators to develop custom shell scripts (often named <b>docker-update</b> or similar) to bundle these actions, especially for personal servers, small projects, or non-orchestrated environments where tools like Kubernetes or Docker Swarm were overkill. The usage of such scripts became a common pattern before more comprehensive orchestration and deployment tools became widely adopted for broader use cases.


title: SEE ALSO
content:
<I>docker pull</I>: Downloads a Docker image from a registry., <I>docker stop</I>: Stops one or more running containers., <I>docker rm</I>: Removes one or more stopped containers., <I>docker run</I>: Creates and starts a new container from an image., <I>docker create</I>: Creates a new container but does not start it., <I>docker update</I>: Updates configuration (e.g., restart policy, resources) of one or more running containers (not images)., <I>docker compose pull</I>: Pulls service images defined in a Docker Compose file., <I>docker compose up</I>: Creates, starts, and runs containers as defined in a Docker Compose file, often with an implicit pull of new images., <I>docker ps</I>: Lists running containers., <I>docker images</I>: Lists Docker images., <I>docker volume</I>: Manages Docker volumes (crucial for data persistence).


title: PARAMETERS
content:
<b>create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new volume. <br>Usage: <b>docker volume create</b> [<i>OPTIONS</i>] [<i>VOLUME_NAME</i>]<br>Common Options: <i>-d, --driver</i> (specify volume driver, e.g., 'local'), <i>--label</i> (set metadata), <i>--opt</i> (set driver-specific options).<br><br><b>ls</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all existing volumes. <br>Usage: <b>docker volume ls</b> [<i>OPTIONS</i>]<br>Common Options: <i>-f, --filter</i> (filter output), <i>--format</i> (pretty-print using Go template), <i>-q, --quiet</i> (only display volume names).<br><br><b>inspect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about one or more volumes. <br>Usage: <b>docker volume inspect</b> [<i>OPTIONS</i>] <i>VOLUME</i> [<i>VOLUME...</i>]<br>Common Options: <i>-f, --format</i> (pretty-print using Go template).<br><br><b>rm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes one or more volumes. <br>Usage: <b>docker volume rm</b> [<i>OPTIONS</i>] <i>VOLUME</i> [<i>VOLUME...</i>]<br>Common Options: <i>-f, --force</i> (force removal of a volume, even if in use).<br><br><b>prune</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all unused local volumes. <br>Usage: <b>docker volume prune</b> [<i>OPTIONS</i>]<br>Common Options: <i>-f, --force</i> (do not prompt for confirmation), <i>--filter</i> (filter volumes to prune).<br><br>


title: DESCRIPTION
content:
<i>docker volume</i> provides commands to manage data volumes, which are the preferred mechanism for persisting data generated by and used by Docker containers. Volumes are independent storage units managed by Docker, ensuring data persists even after containers are stopped or removed. They offer better performance, portability, and backup capabilities compared to bind mounts. This command allows users to create new volumes with specific drivers and options, list existing ones, inspect their detailed configuration and usage, remove them permanently, and prune unused volumes to reclaim disk space on the Docker host. It is a crucial tool for managing stateful applications within the Docker ecosystem.


title: CAVEATS
content:
Volumes consume disk space on the Docker host; regularly pruning unused volumes is recommended. <br>Removing a volume is a permanent action and deletes all associated data. Use with caution. <br>The default 'local' driver stores data directly on the host's filesystem; other drivers can integrate with network storage solutions. <br>Managing file permissions within volumes can sometimes be complex, often requiring consideration of the user/group IDs inside the container.


title: VOLUME DRIVERS
content:
<i>docker volume</i> supports different <i>volume drivers</i> (e.g., 'local', or third-party plugins). Drivers determine where and how the volume's data is stored, enabling capabilities like network storage, cloud storage integration, or advanced data management features. The default driver is 'local', which stores volumes on the Docker host's filesystem.


title: DATA PERSISTENCE
content:
Volumes are designed for data persistence. Unlike data stored within a container's writable layer, data in a volume exists independently of the container's lifecycle. This means data can be safely shared between multiple containers, backed up, or migrated without being affected by container creation, stopping, or removal.


title: HISTORY
content:
The concept of Docker volumes was introduced early in Docker's development as a more robust and portable alternative to basic bind mounts for managing persistent data. Over time, it evolved to support various volume drivers, allowing integration with diverse storage backends beyond the local filesystem. Its usage became central to deploying stateful applications reliably within the Docker ecosystem.


title: SYNOPSIS
content:
<b>doctl account</b> <I>subcommand</I> [<I>flags</I>]<br><br><b>doctl account get</b> [<I>flags</I>]<br><b>doctl account rate-limit</b> [<I>flags</I>]


title: PARAMETERS
content:
<b><b>--access-token</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;DigitalOcean API access token. Can also be set via the <b>DIGITALOCEAN_ACCESS_TOKEN</b> environment variable.<br><br><b><b>--config</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the <b>doctl</b> configuration file. Defaults to <i>$HOME/.config/doctl/config.yaml</i>.<br><br><b><b>--format</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify columns to include in the output, separated by commas (e.g., <i>"Email,DropletLimit"</i>). This flag is inherited from the main <b>doctl</b> command.<br><br><b><b>--no-header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the header row in tabular output. This flag is inherited from the main <b>doctl</b> command.<br><br><b><b>--output</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format: <i>text</i> (default) or <i>json</i>. This flag is inherited from the main <b>doctl</b> command.<br><br><b><b>--trace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable tracing of API requests, showing HTTP request/response details. This flag is inherited from the main <b>doctl</b> command.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output for more detailed command execution information. This flag is inherited from the main <b>doctl</b> command.<br><br>


title: DESCRIPTION
content:
<p>The <b>doctl</b> command-line interface is the official tool for interacting with the DigitalOcean API. The <b>doctl account</b> subcommand is specifically designed to retrieve information about the currently authenticated DigitalOcean account and its associated API rate limits. It provides a quick and easy way to verify the active user, check the account's status, and monitor API consumption directly from the terminal.</p><br><p>This subcommand is crucial for administrators and developers working with DigitalOcean resources, allowing them to gain insights into their account's overall health and adherence to API limits. It offers high-level details such as the account's email, droplet limit, email verification status, and UUID, without exposing overly sensitive billing information. The primary sub-subcommands are <b>get</b>, which fetches general account details, and <b>rate-limit</b>, which displays the remaining, limit, and reset time for the API rate limits.</p>


title: CAVEATS
content:
Using <b>doctl account</b> requires a valid DigitalOcean API token with at least read permissions for your account. The command needs an active internet connection to communicate with the DigitalOcean API. The information returned is strictly limited by the scope and permissions granted to the API token used for authentication. Sensitive billing details like credit card numbers are not exposed through this command for security reasons.


title: USAGE EXAMPLES
content:
Here are some common usage examples for <b>doctl account</b>:<br><br><b><I>1. Retrieve general account information:</I></b><br><code>doctl account get</code><br><br><b><I>2. Check API rate limits:</I></b><br><code>doctl account rate-limit</code><br><br><b><I>3. Get account information in JSON format:</I></b><br><code>doctl account get --output json</code><br><br><b><I>4. Display specific account columns (e.g., email and UUID):</I></b><br><code>doctl account get --format "Email,UUID"</code>


title: AUTHENTICATION (API TOKEN)
content:
To use <b>doctl</b>, you need a DigitalOcean API token. You can generate one from the DigitalOcean Control Panel under <i>API > Tokens/Keys</i>. Once generated, you can configure <b>doctl</b> by running <code>doctl auth init</code> and following the prompts, or by setting the <b>DIGITALOCEAN_ACCESS_TOKEN</b> environment variable, or by passing it directly with the <b>--access-token</b> flag.


title: HISTORY
content:
The <b>doctl</b> command-line tool was developed by DigitalOcean to provide a programmatic interface for managing their cloud resources. The <b>account</b> subcommand has been a fundamental component since the early releases of <b>doctl</b>, offering users essential insights into their DigitalOcean account status and API consumption. Its evolution has paralleled the growth and diversification of DigitalOcean's services, continuously integrating new features and improving usability for managing account-specific information.


title: SYNOPSIS
content:
<b><code>doctl apps [command] [options]</code></b><br><br>Common commands and their general syntax:<br><b><code>doctl apps list</code></b><br><b><code>doctl apps get <i><app-id></i></code></b><br><b><code>doctl apps create --spec <i><path-to-spec.yaml></i></code></b><br><b><code>doctl apps deploy <i><app-id></i></code></b><br><b><code>doctl apps update <i><app-id></i> --spec <i><path-to-new-spec.yaml></i></code></b><br><b><code>doctl apps delete <i><app-id></i></code></b><br><b><code>doctl apps logs <i><app-id></i></code></b>


title: PARAMETERS
content:
<b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Lists all applications associated with your DigitalOcean account.</i><br><br><b>get <i><app-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Retrieves detailed information about a specific application using its ID.</i><br><br><b>create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Creates a new application. This command typically requires an application specification file (YAML/JSON) or interactive input.</i><br><br><b>deploy <i><app-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Initiates a new deployment for an existing application.</i><br><br><b>update <i><app-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Updates an existing application's specification. Requires an application ID and usually a new specification file.</i><br><br><b>delete <i><app-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Deletes an application. This action is irreversible and removes all associated resources.</i><br><br><b>logs <i><app-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Streams or fetches logs for a specified application or its components.</i><br><br><b>spec</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Manages application specifications. Subcommands include <code>get</code> (to retrieve a spec), <code>validate</code> (to check a spec's syntax), and <code>generate</code> (to create a basic spec).</i><br><br><b>proposals</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Manages app proposals, which allow you to preview app changes before applying them.</i><br><br><b>rollback <i><app-id></i> <i><deployment-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Rolls back an application to a previous successful deployment.</i><br><br><b>cancel-deployment <i><app-id></i> <i><deployment-id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Cancels a running deployment for an application.</i><br><br>


title: DESCRIPTION
content:
The <b><code>doctl apps</code></b> command is the primary interface for managing <b>DigitalOcean App Platform</b> applications directly from the command line.<br>It allows users to perform a wide range of operations on their applications, including listing existing applications, retrieving detailed information about a specific application, creating new applications from source code repositories or OCI images, deploying new versions of applications, monitoring deployments, and managing application components (services, workers, jobs, static sites, databases).<br><br>This command streamlines the CI/CD workflow by enabling automation of app deployments and configuration changes, making it an essential tool for developers and DevOps engineers working with DigitalOcean.


title: CAVEATS
content:
<ul><li>Requires a properly configured <b><code>doctl</code></b> CLI with a valid DigitalOcean API token.</li><li>Deleting an application with <b><code>doctl apps delete</code></b> is irreversible and will remove all associated resources and data.</li><li>Advanced operations like <b><code>create</code></b> and <b><code>update</code></b> heavily rely on a correct understanding and construction of <b>App Platform</b> specification files (YAML/JSON).</li></ul>


title: APPLICATION SPECIFICATION (APP SPEC)
content:
Many powerful operations with <b><code>doctl apps</code></b>, especially <b><code>create</code></b> and <b><code>update</code></b>, are driven by an <b>Application Specification</b> file (typically <code>app.yaml</code> or <code>app.json</code>). This declarative configuration defines your entire application, including its components (services, workers, static sites, jobs, databases), environment variables, build commands, and more. Proficiency with the <b>App Spec</b> is crucial for advanced usage and automation.


title: DEPLOYMENT LIFECYCLE MANAGEMENT
content:
The <b><code>doctl apps</code></b> command suite provides extensive control over the application deployment lifecycle. Commands like <b><code>deploy</code></b> initiate new builds and deployments, <b><code>logs</code></b> helps in monitoring and debugging, and <b><code>rollback</code></b> offers a quick way to revert to a previous stable state. This makes <b><code>doctl apps</code></b> a cornerstone for integrating <b>DigitalOcean App Platform</b> into CI/CD pipelines.


title: HISTORY
content:
The <b>DigitalOcean App Platform</b> was officially launched in October 2020. The <b><code>doctl apps</code></b> command and its comprehensive set of subcommands were introduced concurrently to provide command-line management capabilities for this new service. Since its inception, the command has been continuously updated to reflect new features and functionalities added to the <b>App Platform</b>, becoming an indispensable tool for automating and managing application deployments on DigitalOcean.


title: SYNOPSIS
content:
<b>doctl auth</b> <I>command</I> [<I>options</I>] [<I>arguments</I>]<br><br>Common <b>doctl auth</b> commands:<br>&nbsp;&nbsp;<b>doctl auth init</b> [--access-token <I>token</I>] [--context <I>name</I>]<br>&nbsp;&nbsp;<b>doctl auth current</b><br>&nbsp;&nbsp;<b>doctl auth list</b><br>&nbsp;&nbsp;<b>doctl auth switch</b> <I>context-name</I><br>&nbsp;&nbsp;<b>doctl auth remove</b> <I>context-name</I>


title: PARAMETERS
content:
<b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes a new or default authentication context, often by prompting for a DigitalOcean API access token.<br><br><b>current</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the name of the currently active authentication context.<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all configured authentication contexts.<br><br><b>switch <I>context-name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the active authentication context to the specified <i>context-name</i>.<br><br><b>remove <I>context-name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the specified authentication context from <b>doctl</b>'s configuration.<br><br><b>--access-token <I>token</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional, for init)</i> Specifies the DigitalOcean API access token directly, bypassing the interactive prompt. <b>Caution:</b> Providing tokens on the command line may expose them in shell history.<br><br><b>--context <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional, for init, switch, remove)</i> Specifies the name for a new context during initialization, or identifies the context to switch to or remove.<br><br>


title: DESCRIPTION
content:
The <b>doctl auth</b> command group is responsible for configuring and managing authentication to the DigitalOcean API for the <b>doctl</b> command-line client.<br><br>It allows users to log in with their DigitalOcean API access tokens, set up and switch between different authentication contexts (e.g., for multiple DigitalOcean accounts or projects), and list or remove existing contexts. The primary use case is <b>doctl auth init</b>, which guides the user through providing an API token and saves it securely for future commands. This ensures that subsequent <b>doctl</b> commands can interact with DigitalOcean resources on behalf of the authenticated user without needing to re-enter credentials.


title: CAVEATS
content:
<b>Security of API Tokens:</b> DigitalOcean API tokens grant programmatic access to your account. Treat them like passwords. Avoid hardcoding them or exposing them in public repositories. Using the <b>--access-token</b> flag on the command line can leave the token visible in your shell's command history.<br><br><b>Context Management:</b> Carefully manage multiple contexts to ensure you are interacting with the correct DigitalOcean account or project, especially when running automated scripts.


title: OBTAINING A DIGITALOCEAN API TOKEN
content:
To use <b>doctl auth init</b>, you need a DigitalOcean API token. These can be generated from the DigitalOcean Cloud Control Panel under <i>API</i> > <i>Tokens/Keys</i>. It is recommended to generate a new token for <b>doctl</b> with appropriate read/write permissions depending on your intended usage.


title: UNDERSTANDING CONTEXTS
content:
A <b>doctl</b> 'context' is a named configuration profile that stores an API token and optionally other settings. It allows you to quickly switch between different DigitalOcean accounts or sets of permissions without re-authenticating each time. For example, you might have contexts for 'personal-account', 'work-project-A', and 'staging-environment'.


title: HISTORY
content:
<b>doctl</b> is the official command-line interface for the DigitalOcean API, developed and maintained by DigitalOcean itself. The <b>doctl auth</b> subcommand is a foundational component, introduced early in <b>doctl</b>'s development lifecycle, as robust authentication management is critical for interacting with cloud resources. Its design reflects the need for both simplicity (easy initial setup) and flexibility (managing multiple contexts for different projects or teams).


title: PARAMETERS
content:
<b><b>--access-token</b> <i>&lt;token&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a DigitalOcean API personal access token for authentication. Overrides any token set via <i>doctl auth init</i> or environment variables.<br><br><b><b>--config</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom configuration file path for <i>doctl</i>. Default is usually <i>~/.config/doctl/config.yaml</i>.<br><br><b><b>--format</b> <i>&lt;columns&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Columns to include in the output when using text format (e.g., 'ID,Name,Status'). Not directly applicable to <i>balance get</i> output as it's not a list of resources.<br><br><b><b>--no-header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents printing of table headers for text output. Also not directly applicable to <i>balance get</i> output which is a single record.<br><br><b><b>--output</b> <i>&lt;format&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output format. Supported formats include <i>json</i>, <i>text</i>, <i>yaml</i>, and <i>csv</i>. Defaults to <i>text</i>.<br><br><b><b>--trace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes a tracing header in API requests, useful for debugging API calls and communication with DigitalOcean.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing more details about command execution, including API request URLs.<br><br>


title: DESCRIPTION
content:
The <i><b>doctl balance get</b></i> command is a crucial subcommand of the official DigitalOcean CLI client, <i><b>doctl</b></i>. It provides users with a direct and programmatic way to retrieve their current outstanding account balance, month-to-date usage, and any remaining account credit. This functionality is essential for monitoring cloud infrastructure spending, tracking resource consumption, and understanding billing cycles without needing to access the DigitalOcean control panel. The command's output, which can be formatted as JSON, text, or YAML, typically includes the current month's usage, total account balance, the timestamp of the last update, and the start and end dates of the current billing period. It integrates seamlessly into scripting and automation workflows for financial oversight.


title: CAVEATS
content:
The term 'doctl-balance' is often used conceptually to refer to the functionality provided by the <i><b>doctl balance get</b></i> command. It is not a standalone executable. <br>The command requires the <i><b>doctl</b></i> CLI to be installed and properly configured with a DigitalOcean API token that has read access to account information. <br>Balance information is subject to the update frequency of DigitalOcean's billing system and may not reflect real-time changes instantaneously.


title: COMMAND STRUCTURE CLARIFICATION
content:
The command you are asking about, often referred to as 'doctl-balance', is actually executed as <i><b>doctl balance get</b></i>. <i><b>doctl</b></i> is the main command-line interface for DigitalOcean, <i><b>balance</b></i> is a subcommand, and <i><b>get</b></i> is the specific action to retrieve balance information. This structure is common in modern CLIs where a single executable manages multiple related functionalities.


title: API TOKEN REQUIREMENTS
content:
To successfully use <i><b>doctl balance get</b></i>, an active DigitalOcean API token is required. This token must have at least read access to account information. It can be configured globally using <i><b>doctl auth init</b></i>, which stores it securely, or passed directly with the <i><b>--access-token</b></i> flag for single-command execution or in environments where global configuration is not preferred.


title: HISTORY
content:
The <i><b>doctl</b></i> CLI was developed by DigitalOcean to empower developers with a powerful command-line interface for managing their cloud resources. The <i><b>balance</b></i> subcommand, specifically its <i><b>get</b></i> action, has been a foundational component since the early stages of <i><b>doctl</b></i>'s development. Its inclusion underscores DigitalOcean's commitment to transparency and providing users with direct access to critical billing and usage information, facilitating better financial management and integration into automated workflows.


title: SYNOPSIS
content:
<b>doctl compute droplet</b> <I>action</I> [<i>arguments...</i>] [<i>flags...</i>]<br><br>Common actions include:<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>create</b> <I>name</I> --image <I>image-slug</I> --size <I>size-slug</I> --region <I>region-slug</I> [<i>flags...</i>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>list</b> [<i>flags...</i>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>get</b> <I>droplet-id</I> [<i>flags...</i>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>delete</b> <I>droplet-id</I> [<i>flags...</i>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>actions</b> <I>action-type</I> <I>droplet-id</I> [<i>flags...</i>]


title: PARAMETERS
content:
<b><b>create</b> action parameters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parameters for creating a new Droplet.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--name</b> <I>&lt;name&gt;</I>: The desired name for the new Droplet.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--image</b> <I>&lt;image-slug|image-id&gt;</I>: The operating system image or snapshot ID to use (e.g., 'ubuntu-20-04-x64').<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--size</b> <I>&lt;size-slug&gt;</I>: The Droplet size (e.g., 's-1vcpu-1gb').<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--region</b> <I>&lt;region-slug&gt;</I>: The datacenter region where the Droplet will be created (e.g., 'nyc1').<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--ssh-keys</b> <I>&lt;fingerprint|id,...&gt;</I>: Comma-separated list of SSH key fingerprints or IDs to add.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--user-data</b> <I>&lt;path|string&gt;</I>: Path to a file or string containing user data (cloud-init) for customization.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--vpc-uuid</b> <I>&lt;uuid&gt;</I>: UUID of the VPC network to assign the Droplet to.<br><br><b><b>list</b> action parameters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parameters for listing existing Droplets.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--format</b> <I>&lt;columns&gt;</I>: Comma-separated list of columns to display (e.g., 'ID,Name,PublicIPv4,Status').<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--no-header</b>: Suppress the table header in output.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--output</b> <I>&lt;json|yaml|text&gt;</I>: Specify the output format.<br><br><b><b>get</b> action parameters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parameters for retrieving detailed information about a single Droplet.<br>&nbsp;&nbsp;&nbsp;&nbsp;<I>&lt;droplet-id&gt;</I>: The numeric ID of the Droplet to inspect.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--format</b> <I>&lt;columns&gt;</I>: Similar to <b>list</b>, specifies columns for output.<br><br><b><b>delete</b> action parameters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parameters for deleting one or more Droplets.<br>&nbsp;&nbsp;&nbsp;&nbsp;<I>&lt;droplet-id|droplet-name&gt;</I>: The ID(s) or name(s) of the Droplet(s) to delete.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--force</b>: Skip the interactive confirmation prompt.<br><br><b><b>actions</b> action parameters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Parameters for performing specific operations on a Droplet.<br>&nbsp;&nbsp;&nbsp;&nbsp;<I>&lt;action-type&gt;</I>: The type of action to perform (e.g., 'power_on', 'reboot', 'snapshot', 'resize', 'rebuild').<br>&nbsp;&nbsp;&nbsp;&nbsp;<I>&lt;droplet-id&gt;</I>: The ID of the Droplet to apply the action to.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--image</b> <I>&lt;image-slug|image-id&gt;</I>: (Specific to 'rebuild' action) The new image for rebuilding.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--size</b> <I>&lt;size-slug&gt;</I>: (Specific to 'resize' action) The new size slug for the Droplet.<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--name</b> <I>&lt;snapshot-name&gt;</I>: (Specific to 'snapshot' action) Name for the new snapshot.<br><br>


title: DESCRIPTION
content:
The <b>doctl compute droplet</b> command is a crucial part of the DigitalOcean command-line client (<b>doctl</b>) used for comprehensive management of DigitalOcean Droplets. Droplets are scalable Linux-based virtual machines offered by DigitalOcean. This subcommand allows users to perform a wide array of operations including creating new Droplets, listing existing ones, retrieving detailed information about a specific Droplet, deleting Droplets, and executing various Droplet-specific actions like powering them on/off, rebooting, resizing, rebuilding, taking snapshots, and managing their associated backups, floating IPs, and firewall rules. It provides a programmatic interface to interact with the DigitalOcean Droplet API, enabling automation and scripting of infrastructure management tasks.


title: CAVEATS
content:
<b>API Rate Limits:</b> DigitalOcean API has rate limits. Frequent requests might lead to temporary blocking.<br><b>Permissions:</b> Ensure your DigitalOcean API token has the necessary read/write permissions for Droplet management.<br><b>Cost Implications:</b> Creating, resizing, or enabling features for Droplets will incur costs. Always verify actions.<br><b>Asynchronous Operations:</b> Many Droplet actions (like create, resize, snapshot) are asynchronous. The command might return before the action is fully completed.<br><b>Data Loss:</b> Deleting a Droplet is permanent and results in data loss. Always back up critical data.


title: AUTHENTICATION
content:
<b>doctl</b> requires authentication via a DigitalOcean API token. This is typically configured using <b>doctl auth init</b> or by setting the <b>DIGITALOCEAN_ACCESS_TOKEN</b> environment variable.


title: OUTPUT FORMATTING FOR SCRIPTING
content:
<b>doctl</b> commands, including <b>compute droplet</b>, offer flexible output options using <b>--format</b>, <b>--output json</b>, or <b>--output yaml</b> which are excellent for scripting and integration with other tools.


title: INTERACTIVE PROMPTS AND FORCE FLAG
content:
Many destructive operations (e.g., <b>delete</b>) include interactive prompts for confirmation. These can be bypassed for automation using the <b>--force</b> flag.


title: HISTORY
content:
The <b>doctl</b> command-line interface was developed by DigitalOcean to provide a powerful, user-friendly, and scriptable way to interact with their cloud platform. It has evolved significantly since its initial release, adding support for new DigitalOcean products and features, and improving command syntax and output. The <b>compute droplet</b> subcommand has been a core component from early versions, reflecting the Droplet's central role in the DigitalOcean ecosystem, continuously updated to support new Droplet capabilities like VPC networking, SSH key management, and user data integration.


title: SEE ALSO
content:
doctl compute volume(1), doctl compute snapshot(1), doctl compute firewall(1), doctl auth(1), doctl account(1)


title: SYNOPSIS
content:
<b>doctl databases</b> <i>&lt;command&gt;</i> [<i>options</i>]<br><br>The <b>doctl databases</b> command is a subcommand group of the <i>doctl</i> CLI, used to interact with DigitalOcean's Managed Databases service. Common <i>&lt;commands&gt;</i> include:<br><b>&nbsp;&nbsp;create</b>: Create a new managed database cluster.<br><b>&nbsp;&nbsp;list</b>: List all managed database clusters.<br><b>&nbsp;&nbsp;get</b>: Retrieve details for a specific cluster.<br><b>&nbsp;&nbsp;update</b>: Modify an existing database cluster's configuration.<br><b>&nbsp;&nbsp;delete</b>: Permanently delete a database cluster.<br><b>&nbsp;&nbsp;connection</b>: Show connection details for a database cluster.<br><b>&nbsp;&nbsp;users</b>: Manage database users within a cluster.<br><b>&nbsp;&nbsp;pools</b>: Manage PostgreSQL connection pools.<br><b>&nbsp;&nbsp;replica</b>: Manage read-only replicas for a database cluster.<br><br>Example Usage:<br><i>&nbsp;&nbsp;doctl databases create --engine pg --version 14 --size s-2vcpu-4gb --region nyc3 --name my-pg-db</i><br><i>&nbsp;&nbsp;doctl databases list --format UUID,Name,Engine,Region,Status</i><br><i>&nbsp;&nbsp;doctl databases get my-pg-db</i>


title: PARAMETERS
content:
<b><i>--format</i> <i>&lt;columns&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of columns to display in the output. Useful for <i>list</i> and <i>get</i> commands to customize table views.<br><br><b><i>--output</i> <i>&lt;json|yaml|text&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format. Defaults to human-readable text for tables; JSON or YAML provide structured data.<br><br><b><i>--no-headers</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress table headers from the output, often used for scripting.<br><br><b><i>--engine</i> <i>&lt;engine&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the database engine (e.g., <i>pg</i> for PostgreSQL, <i>mysql</i> for MySQL, <i>redis</i> for Redis, <i>mongodb</i> for MongoDB). Required for <i>create</i>.<br><br><b><i>--version</i> <i>&lt;version&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the specific version of the database engine (e.g., <i>14</i> for PostgreSQL, <i>8</i> for MySQL). Required for <i>create</i>.<br><br><b><i>--size</i> <i>&lt;slug&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines the resource plan (CPU, RAM, storage) for the cluster (e.g., <i>s-2vcpu-4gb</i>). Required for <i>create</i>; also used with <i>update</i> and <i>replica</i>.<br><br><b><i>--region</i> <i>&lt;slug&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the DigitalOcean datacenter region where the cluster will be deployed (e.g., <i>nyc3</i>, <i>fra1</i>). Required for <i>create</i>; also used for <i>replica</i>.<br><br><b><i>--name</i> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A unique, user-friendly name for the database cluster. Required for <i>create</i>; used to identify clusters in <i>get</i>, <i>update</i>, <i>delete</i>, and related subcommands.<br><br><b><i>--num-nodes</i> <i>&lt;count&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired number of nodes in the database cluster. Defaults to 1 for most engines. Used for <i>create</i> and <i>update</i>.<br><br><b><i>--private-network</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables private network (VPC) access for the database cluster, enhancing security and reducing egress costs. Used for <i>create</i> and <i>update</i>.<br><br><b><i>--force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypasses the confirmation prompt for destructive operations like <i>delete</i>. Use with caution.<br><br>


title: DESCRIPTION
content:
<i>doctl databases</i> is the command group within the DigitalOcean command-line interface (<i>doctl</i>) used to interact with and manage DigitalOcean Managed Databases. It allows users to create, list, retrieve details for, update, and delete database clusters, as well as manage users, connection pools, and replica nodes for various database engines like PostgreSQL, MySQL, Redis, and MongoDB. This command group simplifies database operations directly from the terminal, enabling automation and scripting of database lifecycle management for cloud-based database instances.


title: CAVEATS
content:
Usage of <i>doctl databases</i> requires a DigitalOcean account and an API token with appropriate read/write permissions for database resources. Creating and operating database clusters incurs charges based on their size, number of nodes, and data transfer. Deleting a database cluster is an irreversible action that will permanently remove all associated data and backups.


title: DIGITALOCEAN API TOKEN
content:
<i>doctl</i> authenticates using a DigitalOcean API token. This token can be configured using <i>doctl auth init</i> or by setting the <i>DIGITALOCEAN_ACCESS_TOKEN</i> environment variable. Ensure the token has the necessary permissions to manage databases.


title: MANAGED DATABASE LIFECYCLE
content:
<i>doctl databases</i> supports the full lifecycle of managed databases, from creation and configuration (e.g., size, region, private networking) to user and connection pool management, read replica creation, and eventual deletion. It also provides commands to retrieve crucial connection details and manage database-specific settings.


title: HISTORY
content:
<i>doctl</i>, the official command-line client for the DigitalOcean API, has been continuously developed to provide a comprehensive interface for managing cloud resources. The <i>databases</i> command group was progressively introduced as DigitalOcean expanded its offering of managed database services (PostgreSQL, MySQL, Redis, MongoDB), integrating seamless CLI management into the <i>doctl</i> suite. This integration allows developers and system administrators to automate database provisioning, scaling, and maintenance tasks directly from their terminals or scripts.


title: SYNOPSIS
content:
<b>doctl databases firewalls</b> <i>&lt;command&gt;</i> [<i>&lt;flags&gt;</i>]<br><i>Common subcommands include:</i><br><b>doctl databases firewalls list</b> <i>&lt;database-id&gt;</i><br><b>doctl databases firewalls add-rule</b> <i>&lt;database-id&gt;</i> <i>&lt;flags&gt;</i><br><b>doctl databases firewalls remove-rule</b> <i>&lt;database-id&gt;</i> <i>&lt;flags&gt;</i><br><b>doctl databases firewalls create</b> <i>&lt;database-id&gt;</i> <i>&lt;flags&gt;</i><br><b>doctl databases firewalls delete</b> <i>&lt;database-id&gt;</i><br><b>doctl databases firewalls get</b> <i>&lt;database-id&gt;</i>


title: PARAMETERS
content:
<b><i>list</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Retrieves and displays all currently configured firewall rules for a specified database cluster.</i><br><br><b><i>add-rule</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Adds a new inbound firewall rule to a database cluster's existing firewall configuration. This rule specifies a permitted source (IP, CIDR, Droplet, or Kubernetes cluster).</i><br><br><b><i>remove-rule</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Deletes an existing inbound firewall rule from a database cluster's firewall configuration based on its value and type.</i><br><br><b><i>create</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Initializes and applies a new firewall configuration to a database cluster, optionally including an initial set of rules.</i><br><br><b><i>delete</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Removes the entire firewall configuration for a specified database cluster, making it accessible from all IPs (unless other network restrictions are in place).</i><br><br><b><i>get</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Fetches and displays detailed information about the firewall configuration of a database cluster, including all its associated rules.</i><br><br>


title: DESCRIPTION
content:
<i>The <b>doctl databases firewalls</b> command group is an integral part of the DigitalOcean command-line interface (<b>doctl</b>), providing comprehensive control over network access to your managed database clusters.<br>This command set allows users to configure and manage inbound firewall rules for various database engines, including PostgreSQL, MySQL, Redis, and MongoDB.<br>It enables specifying which IP addresses, IP ranges (CIDR), DigitalOcean Droplets, or Kubernetes clusters are permitted to establish connections to your database instances.<br>By utilizing these commands, users can secure their databases by enforcing network isolation and preventing unauthorized access, which is crucial for maintaining data security and compliance.<br>The streamlined terminal-based management facilitates automation, scripting, and integration into CI/CD pipelines for robust infrastructure-as-code practices.</i>


title: CAVEATS
content:
<i><br><b>1. doctl Installation and Configuration:</b> Requires the <b>doctl</b> CLI tool to be installed and properly configured with a valid DigitalOcean API token.<br><b>2. Database ID Requirement:</b> Most operations necessitate the unique identifier (UUID) of the target database cluster. This ID can be obtained via <b>doctl databases list</b>.<br><b>3. Rule Specificity:</b> Firewall rules are highly specific. Ensure correct IP addresses, CIDR ranges, Droplet IDs, or Kubernetes URNs are provided to avoid connectivity issues.<br><b>4. Ingress Control Only:</b> These firewalls control inbound network traffic to the database. They do not manage outbound connections from the database.<br><b>5. Impact of Deletion:</b> Deleting a database firewall (using <b>delete</b>) typically makes the database publicly accessible from any IP address unless other network-level security measures are active.<br></i>


title: <I>PERMISSIONS AND API TOKEN SCOPE</I>
content:
<i>To manage database firewalls, your DigitalOcean API token must have appropriate read/write permissions for database resources. Tokens with more restrictive scopes might not be able to perform all operations.</i>


title: <I>SECURITY BEST PRACTICES</I>
content:
<i>Always adhere to the principle of least privilege when configuring firewall rules. Only allow access from known and necessary sources to minimize the attack surface and enhance database security. Regularly review and update your firewall rules.</i>


title: HISTORY
content:
<i>The development of the <b>doctl</b> command-line interface closely mirrors the expansion of DigitalOcean's cloud offerings. As DigitalOcean introduced and matured its managed database services, the need for programmatic interaction became paramount.<br>The <b>doctl databases firewalls</b> command group was integrated into the CLI to empower users to manage database security settings directly from their terminal.<br>This evolution aligns with the industry trend towards infrastructure-as-code and automation, enabling developers and operations teams to embed database security configurations into their automated deployment and management workflows, significantly enhancing operational efficiency and security posture.</i>


title: SEE ALSO
content:
<b>doctl databases</b>(1): <i>For general management and listing of DigitalOcean managed database clusters.</i>, <b>doctl compute firewall</b>(1): <i>For managing network firewalls specifically for DigitalOcean Droplets and other compute resources.</i>


title: SYNOPSIS
content:
<b>doctl databases maintenance-window get</b> <i>&lt;database-cluster-uuid&gt;</i><br><i>Get the current maintenance window settings for a database cluster.</i><br><br><b>doctl databases maintenance-window update</b> <i>&lt;database-cluster-uuid&gt;</i> <b>--day</b> <i>&lt;day-of-week&gt;</i> <b>--hour</b> <i>&lt;hour-of-day&gt;</i><br><i>Update the maintenance window for a database cluster.</i><br><i>&lt;day-of-week&gt;</i>: e.g., <i>monday, tuesday, ..., sunday</i><br><i>&lt;hour-of-day&gt;</i>: e.g., <i>0-23 (UTC)</i>


title: PARAMETERS
content:
<b><i>&lt;database-cluster-uuid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier (UUID) of the DigitalOcean database cluster for which to manage the maintenance window. This UUID is a mandatory argument and can be obtained by listing your database clusters using `<b>doctl databases list</b>`.<br><br><b><b>--day</b> <i>&lt;day-of-week&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Required for the `<b>update</b>` command. Specifies the preferred day of the week for the maintenance window. Valid string values include `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, and `sunday`.<br><br><b><b>--hour</b> <i>&lt;hour-of-day&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Required for the `<b>update</b>` command. Specifies the preferred hour of the day (in <b>UTC</b>) for the maintenance window. Valid integer values range from `0` (midnight UTC) to `23` (11 PM UTC).<br><br>


title: DESCRIPTION
content:
The `<b>doctl databases maintenance-window</b>` command is a specific subcommand within the official DigitalOcean command-line interface (`<b>doctl</b>`). It is designed to manage the scheduled maintenance windows for DigitalOcean Managed Database Clusters.<br><br>DigitalOcean's Managed Databases regularly receive automated updates, security patches, and minor version upgrades to ensure their stability, security, and performance. These critical operations are typically performed during a designated maintenance window to minimize potential disruption to user applications.<br><br>This command provides users with the ability to both retrieve the current maintenance window settings for a specified database cluster and to update them to a preferred day and hour (in UTC). This granular control allows administrators to align database maintenance with their application's lowest traffic periods, thus optimizing availability and user experience.


title: CAVEATS
content:
<ul><li><b>Impact:</b> Changing the maintenance window directly influences when your database cluster will undergo critical updates and patches. It's crucial to select a time that aligns with your application's lowest traffic or usage periods to minimize potential user impact.</li><li><b>UTC Time Zone:</b> The `--hour` parameter strictly uses Universal Coordinated Time (UTC). Users must convert their desired local time to UTC before setting it to ensure the maintenance occurs at the expected time.</li><li><b>Potential Disruption:</b> While DigitalOcean engineers strive to make updates as non-disruptive as possible, some operations may still lead to brief periods of unavailability or degraded performance during the maintenance window.</li><li><b>Permissions:</b> To successfully update a maintenance window, your DigitalOcean API token used with `<b>doctl</b>` must possess the necessary write permissions for database resources.</li></ul>


title: CHECKING CURRENT SETTINGS
content:
To view the current maintenance window configuration for a specific database cluster, execute the `<b>get</b>` subcommand, replacing <i>&lt;your-database-cluster-uuid&gt;</i> with the actual UUID of your cluster:<br><b>doctl databases maintenance-window get</b> <i>&lt;your-database-cluster-uuid&gt;</i><br>The output will typically display the `day_of_week` and `hour_of_day` (UTC) currently set for that cluster.


title: EXAMPLE USAGE: UPDATING THE MAINTENANCE WINDOW
content:
Suppose you want to set your database cluster with UUID `a1b2c3d4-e5f6-7890-1234-567890abcdef` to have its maintenance window on Sunday at 2 AM UTC. You would use the `<b>update</b>` subcommand as follows:<br><b>doctl databases maintenance-window update</b> <i>a1b2c3d4-e5f6-7890-1234-567890abcdef</i> <b>--day</b> <i>sunday</i> <b>--hour</b> <i>2</i><br>Upon successful execution, `<b>doctl</b>` will typically confirm the update, and the new settings will take effect for the next scheduled maintenance cycle.


title: HISTORY
content:
The `<b>doctl</b>` command-line interface has been developed and continually enhanced by DigitalOcean to offer a robust and programmatic way for users to interact with their cloud infrastructure. The `<b>databases</b>` command group, including the functionality for managing maintenance windows, was introduced as DigitalOcean's Managed Databases offering matured. This feature reflects the growing need for users to have precise control over the operational aspects and lifecycle of their managed database instances, aligning with industry best practices for automated update management and service continuity.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>options</i> subcommand.<br><br>


title: DESCRIPTION
content:
The <i>doctl databases options</i> command retrieves a comprehensive list of all available configuration options for creating DigitalOcean Managed Databases. This includes details on supported database engines (e.g., PostgreSQL, MySQL, Redis, MongoDB) and their available versions, default versions, connection limits, and supported storage sizes. It also provides information on DigitalOcean regions where managed databases can be deployed, including their availability and supported features. Furthermore, it lists the various database cluster sizes (plans) available, detailing their CPU, RAM, disk space, and pricing information. This command is crucial for users needing to programmatically or interactively determine valid parameters before provisioning a new database cluster.


title: CAVEATS
content:
Requires the DigitalOcean command-line client (<i>doctl</i>) to be installed and properly authenticated with a DigitalOcean API token. The output is always in JSON format, which can be parsed by other tools or scripts. The specific options (e.g., engine versions, regions, sizes) are dynamic and reflect DigitalOcean's current offerings, thus may change over time.


title: OUTPUT STRUCTURE
content:
The command's output is a JSON object containing three primary keys:<br><ul><li><b><i>engines</i></b>: Provides details for each supported database engine (e.g., PostgreSQL, MySQL, Redis, MongoDB), including available versions, default version, connection limits per plan, and supported storage sizes.</li><li><b><i>regions</i></b>: Lists DigitalOcean regions where managed databases can be deployed, along with their slug, name, availability, and supported features (i.e., which database engines are available in that region).</li><li><b><i>sizes</i></b>: Describes the different database cluster plans (sizes), detailing their CPU cores, RAM, disk space, and hourly/monthly pricing. Each size also indicates its storage and CPU tier.</li></ul>


title: HISTORY
content:
The <i>doctl</i> command-line tool, developed by DigitalOcean, has evolved significantly since its initial release to support an expanding range of DigitalOcean services. The <i>databases</i> subcommand, and specifically the <i>options</i> command, was introduced to provide programmatic access to the dynamic configuration choices available for Managed Databases, simplifying automation and scripting of database provisioning.


title: SYNOPSIS
content:
<i><b>doctl databases pool</b></i> <I>command</I> <I>database-cluster-id</I> [<I>database-name</I>] [<I>pool-name</I>] [<I>flags</I>]<br><br>Specific command usages:<br><ul><li><i><b>doctl databases pool list</b></i> <I>database-cluster-id</I> <I>database-name</I> [<I>flags</I>]</li><li><i><b>doctl databases pool create</b></i> <I>database-cluster-id</I> <I>database-name</I> <I>pool-name</I> <b>--mode</b> <I>session|transaction|statement</I> <b>--size</b> <I>connections</I> [<I>flags</I>]</li><li><i><b>doctl databases pool get</b></i> <I>database-cluster-id</I> <I>database-name</I> <I>pool-name</I> [<I>flags</I>]</li><li><i><b>doctl databases pool delete</b></i> <I>database-cluster-id</I> <I>database-name</I> <I>pool-name</I> [<I>flags</I>]</li></ul>


title: PARAMETERS
content:
<b><I>database-cluster-id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier (UUID) of the DigitalOcean database cluster.<br><br><b><I>database-name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the specific database within the cluster to which the pool belongs or for which it is created/managed.<br><br><b><I>pool-name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique name given to the connection pool for identification within the specified database.<br><br><b><b>--mode</b> <I>session|transaction|statement</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>create</i> command) Specifies the transaction mode for the connection pool. Defines how the pool manages connections during transactions. Options are <i>session</i> (default), <i>transaction</i>, or <i>statement</i>.<br><br><b><b>--size</b> <I>int</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>create</i> command) Sets the maximum number of connections allowed in the pool. This determines how many simultaneous connections can be active in the pool.<br><br><b><b>-f, --force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>delete</i> command) Forces the deletion of the pool without a confirmation prompt.<br><br><b><b>-o, --output</b> <I>json|csv|text</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format for the command's results. Default is 'text'.<br><br><b><b>--access-token</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;DigitalOcean API access token. Overrides the <i>DO_API_TOKEN</i> environment variable or configured token.<br><br><b><b>--config</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the <i>doctl</i> configuration file. Defaults to <i>$HOME/.config/doctl/config.yaml</i>.<br><br>


title: DESCRIPTION
content:
<i><b>doctl</b></i> is the official command-line interface for the DigitalOcean API, enabling users to interact with and manage their cloud resources directly from the terminal. The <i><b>doctl databases pool</b></i> command specifically focuses on the administration of connection pools for DigitalOcean Managed Databases.<br><br>Database connection pools are a vital feature for optimizing database performance and resource utilization in applications, especially those with high concurrency. They allow applications to reuse existing database connections rather than establishing a new one for every request, significantly reducing overhead, improving response times, and conserving database resources.<br><br>This command provides subcommands to perform essential operations on database pools, including:<br><ul><li>Creating new pools with specified sizes and transaction modes.</li><li>Listing all existing pools for a database to monitor their configurations.</li><li>Retrieving detailed information about a specific pool.</li><li>Deleting pools when they are no longer required.</li></ul>It streamlines the administration of database connection management within the DigitalOcean ecosystem, integrating seamlessly with other <i><b>doctl</b></i> functionalities for comprehensive infrastructure management.


title: CAVEATS
content:
<ul><li>The choice of connection pool mode (<i>session</i>, <i>transaction</i>, <i>statement</i>) has significant implications for application behavior and concurrency; it must align with the application's database transaction model.</li><li>Setting the <i>--size</i> parameter requires careful consideration of the database's capacity and the application's expected concurrency. An excessively large pool can overload the database, while too small a pool can lead to bottlenecks.</li><li>Deleting a connection pool will immediately terminate all active connections associated with it, potentially disrupting applications that are currently using the pool.</li><li>DigitalOcean Managed Databases have underlying resource limits. Creating a large number of pools or pools with very high connection limits might impact overall cluster performance or run into service quotas.</li></ul>


title: AUTHENTICATION
content:
<i><b>doctl</b></i> commands, including <i><b>doctl databases pool</b></i>, require authentication via a DigitalOcean API token. This token can be provided through the <i>DO_API_TOKEN</i> environment variable, specified with the <i>--access-token</i> flag, or configured in the <i>doctl</i> configuration file (typically at <i>~/.config/doctl/config.yaml</i>).


title: ERROR HANDLING
content:
Upon failure, <i><b>doctl</b></i> commands typically return a non-zero exit code. Detailed error messages are usually displayed on the console, providing guidance for troubleshooting API issues, invalid parameters, or resource limitations.


title: SCRIPTING AND AUTOMATION
content:
For scripting and automation purposes, using the <i><b>-o json</b></i> flag is highly recommended. This outputs command results in a structured JSON format, making it easy to parse and process programmatically in various scripting languages.


title: HISTORY
content:
The <i><b>doctl</b></i> command-line tool, developed by DigitalOcean, provides a comprehensive programmatic interface to their cloud platform. Its evolution has paralleled the expansion of DigitalOcean's product ecosystem, including the introduction of Managed Databases. Managed Databases, designed to simplify database administration, offload complex setup and maintenance tasks to DigitalOcean. The <i><b>doctl databases pool</b></i> subcommand was added as part of these efforts, enabling customers to manage this critical performance-enhancing feature directly from their command line. This integration facilitates automation, scripting, and seamless inclusion within CI/CD pipelines, reflecting a broader industry shift towards infrastructure-as-code and API-driven resource management.


title: SEE ALSO
content:
doctl databases(1), doctl databases users(1), doctl databases evict-cache(1), psql(1) (for PostgreSQL databases), mysql(1) (for MySQL databases)


title: SYNOPSIS
content:
<b>doctl databases replica &lt;command&gt; [arguments...] [flags...]</b><br><br>Common commands:<br> &nbsp; <b>doctl databases replica create &lt;cluster-id&gt; --name &lt;replica-name&gt; [flags...]</b><br> &nbsp; <b>doctl databases replica list &lt;cluster-id&gt; [flags...]</b><br> &nbsp; <b>doctl databases replica get &lt;cluster-id&gt; &lt;replica-name&gt; [flags...]</b><br> &nbsp; <b>doctl databases replica delete &lt;cluster-id&gt; &lt;replica-name&gt; [flags...]</b>


title: PARAMETERS
content:
<b><I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific operation to perform on replicas. Common commands include <I>create</I>, <I>list</I>, <I>get</I>, and <I>delete</I>.<br><br><b><I>cluster-id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier of the primary database cluster to which the replica belongs. Required for most subcommands.<br><br><b><I>replica-name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired name for the new replica (for <I>create</I>), or the name of an existing replica to operate on (for <I>get</I>, <I>delete</I>).<br><br><b><b>--name</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Required for the <I>create</I> command. Specifies the name of the new read replica.<br><br><b><b>--region</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional for the <I>create</I> command. Specifies the datacenter region where the read replica will be deployed (e.g., <I>nyc3</I>). If omitted, it defaults to the primary cluster's region.<br><br><b><b>--size</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional for the <I>create</I> command. Specifies the slug of the node size for the replica (e.g., <I>db-s-1vcpu-1gb</I>). If omitted, it defaults to the primary cluster's size.<br><br><b><b>--format</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of columns to display in the output (e.g., <I>ID,Name,Status</I>). Applicable to <I>list</I> and <I>get</I>.<br><br><b><b>--no-header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Boolean flag to suppress table headers in the output. Applicable to <I>list</I> and <I>get</I>.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Boolean flag to output results in JSON format. Applicable to all commands.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Boolean flag to skip confirmation prompts, particularly useful for destructive operations like <I>delete</I>.<br><br>


title: DESCRIPTION
content:
<I>doctl databases replica</I> is a command group within the DigitalOcean CLI (<I>doctl</I>) that provides tools to manage read replicas for your DigitalOcean Managed Databases. Read replicas are asynchronous, read-only copies of your primary database cluster. They are primarily used to scale read-heavy applications, offload analytical queries from the primary database, and improve performance by distributing read traffic across multiple instances. This command group allows users to create, list, retrieve details for, and delete these replicas directly from the command line, integrating seamlessly with DigitalOcean's database service. Key subcommands include <I>create</I> for provisioning new replicas, <I>list</I> to view existing ones, <I>get</I> for detailed information, and <I>delete</I> to remove them.


title: CAVEATS
content:
<b>Read-Only Nature:</b> Read replicas are strictly read-only; no write operations can be performed directly on them.<br><b>Asynchronous Replication:</b> Data replication from the primary to the replica is asynchronous, meaning there might be a slight delay (replication lag) between the primary and the replica.<br><b>Deletion is Permanent:</b> Deleting a read replica is a permanent action and cannot be undone.<br><b>Billing:</b> Read replicas are billed as separate database nodes based on their size and region, adding to your DigitalOcean costs.<br><b>Supported Databases:</b> Read replicas are primarily supported for PostgreSQL and MySQL managed databases. Other database types like Redis may not have the same concept of read replicas.


title: TYPICAL USAGE WORKFLOW
content:
A common workflow involves first creating a primary database cluster using <I>doctl databases create</I>. Once the primary is active, you can then create one or more read replicas using <I>doctl databases replica create</I> to distribute read traffic. You can monitor their status with <I>doctl databases replica list</I> and retrieve detailed information with <I>doctl databases replica get</I>, and delete them when no longer needed with <I>doctl databases replica delete</I>.


title: CROSS-REGION REPLICAS
content:
DigitalOcean supports creating read replicas in a different region than the primary database cluster for enhanced disaster recovery and lower latency for geo-distributed applications. This can be specified using the <B>--region</B> flag during replica creation, provided the chosen regions support this feature for the specific database engine.


title: HISTORY
content:
DigitalOcean introduced Managed Databases as a service to simplify database management for developers. The capability to create read replicas was added to address the growing need for horizontal scaling of read-heavy applications and to offload analytical workloads. The <I>doctl</I> CLI, being the primary programmatic interface for DigitalOcean resources, integrated these database management capabilities, including replica management, as part of its ongoing development to provide comprehensive infrastructure control via the command line.


title: SEE ALSO
content:
<b>doctl(1)</b>, <b>doctl databases(1)</b>, <b>doctl databases create(1)</b>, <b>doctl databases list(1)</b>


title: SYNOPSIS
content:
<B>doctl databases sql-mode get</B> <I>&lt;cluster-id|cluster-name&gt;</I> [options]<br><B>doctl databases sql-mode set</B> <I>&lt;cluster-id|cluster-name&gt;</I> <I>--mode &lt;sql_mode_string&gt;</I> [options]


title: PARAMETERS
content:
<b><I>&lt;cluster-id|cluster-name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Required. Specifies the target database cluster by its unique identifier (UUID) or its user-defined name. Used by both <B>get</B> and <B>set</B> operations.<br><br><b><B>get</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommand to retrieve the current SQL mode set for the specified database cluster.<br><br><b><B>set</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommand to modify the SQL mode for the specified database cluster. Requires the <I>--mode</I> flag.<br><br><b><B>--mode</B> <I>&lt;sql_mode_string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Required when using the <B>set</B> subcommand. A comma-separated string of SQL modes to apply (e.g., <I>STRICT_TRANS_TABLES,NO_ZERO_DATE</I>). To unset all modes, use an empty string.<br><br><b><B>--format</B> <I>&lt;format&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Specifies the output format (e.g., <I>json</I>, <I>yaml</I>, <I>text</I>). Useful for scripting or machine-readable output.<br><br><b><B>--help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Displays help information for the command.<br><br><b><B>--force</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Forces the operation without a confirmation prompt, useful in scripts.<br><br>


title: DESCRIPTION
content:
The <I>doctl-databases-sql-mode</I> command, typically invoked as <B>doctl databases sql-mode</B>, is part of the DigitalOcean CLI tool (<I>doctl</I>) used to manage database clusters. Specifically, this subcommand allows users to view and modify the SQL mode for their DigitalOcean database clusters, primarily relevant for MySQL databases.<br><br>SQL modes are server settings that define how MySQL behaves in various situations, such as validation rules for data, handling of invalid input, and syntax compatibility. They can enforce stricter data integrity rules (e.g., <I>STRICT_TRANS_TABLES</I>), affect how dates and times are handled (<I>NO_ZERO_DATE</I>), or enable compatibility with other SQL standards (<I>ANSI</I>).<br><br>By using this command, administrators can tailor the behavior of their MySQL databases to specific application requirements or compliance standards, ensuring data consistency and predictable operation on their DigitalOcean-managed database instances. It provides a convenient command-line interface for operations that would otherwise require direct SQL queries or database console access.


title: CAVEATS
content:
This command primarily applies to MySQL database clusters on DigitalOcean. SQL modes are a MySQL-specific concept. While DigitalOcean supports PostgreSQL and Redis databases, SQL mode management is not applicable to them in the same way.<br><br>Changing SQL modes can significantly impact application behavior and data integrity. Always test changes in a staging environment before applying them to production databases. Incorrect SQL modes can lead to data truncation, unexpected data conversions, or application errors.<br><br>The <I>doctl</I> CLI must be authenticated and configured to interact with your DigitalOcean account for this command to function.


title: UNDERSTANDING SQL MODES
content:
SQL modes in MySQL allow you to configure the behavior of the database server. They are a set of rules that can be enabled or disabled to enforce stricter data validation, modify how certain SQL constructs are handled, or ensure compatibility with different SQL standards. Common modes include <I>STRICT_TRANS_TABLES</I> (for strict validation), <I>NO_ZERO_DATE</I> (disallows '0000-00-00' as a valid date), and <I>TRADITIONAL</I> (combines several strict modes).


title: IMPACT ON APPLICATIONS
content:
Applications often rely on specific SQL mode settings. For example, legacy applications might expect permissive SQL modes (like <I>ALLOW_INVALID_DATES</I>), while modern applications might require strict modes for better data integrity. Before changing SQL modes, it's crucial to understand how they might affect your application's interaction with the database, especially regarding data insertion, updates, and type conversions.


title: SEE ALSO
content:
doctl(1), doctl databases(1), doctl databases list(1), doctl databases create(1), doctl databases update(1)


title: SYNOPSIS
content:
<b>doctl databases user</b> <i>&lt;command&gt;</i> [<i>&lt;arguments...&gt;</i>] [<i>&lt;flags...&gt;</i>]<br><br>Common <i>commands</i> include:<br><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><b>create</b> <i>&lt;cluster-id&gt; &lt;username&gt;</i> [<i>&lt;flags&gt;</i>]<br><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><b>delete</b> <i>&lt;cluster-id&gt; &lt;username&gt;</i> [<i>&lt;flags&gt;</i>]<br><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><b>get</b> <i>&lt;cluster-id&gt; &lt;username&gt;</i> [<i>&lt;flags&gt;</i>]<br><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><b>list</b> <i>&lt;cluster-id&gt;</i> [<i>&lt;flags&gt;</i>]<br><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><b>reset-password</b> <i>&lt;cluster-id&gt; &lt;username&gt;</i> [<i>&lt;flags&gt;</i>]


title: PARAMETERS
content:
<b><i>&lt;cluster-id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier (UUID) of the DigitalOcean Managed Database cluster. This is a required positional argument for most <i>doctl databases user</i> subcommands.<br><br><b><i>&lt;username&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired name of the database user to create, get, delete, or reset password for. This is a required positional argument for <b>create</b>, <b>delete</b>, <b>get</b>, and <b>reset-password</b> subcommands.<br><br><b><b>--output</b>, <b>-o</b> <i>&lt;format&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format for the command's results (e.g., <i>json</i>, <i>yaml</i>, <i>text</i>, <i>csv</i>). This is a global <i>doctl</i> flag.<br><br><b><b>--format</b> <i>&lt;columns&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of columns to include in <i>text</i> or <i>csv</i> output. This is a global <i>doctl</i> flag.<br><br><b><b>--no-header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents printing of the header row in table output. This is a global <i>doctl</i> flag.<br><br><b><b>--force</b>, <b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypasses confirmation prompts for destructive actions (e.g., deleting a user). Use with caution. This is a global <i>doctl</i> flag.<br><br><b><b>--api-token</b> <i>&lt;token&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The DigitalOcean API access token to use for authentication. Can also be set via environment variable or <i>doctl auth init</i>. This is a global <i>doctl</i> flag.<br><br><b><b>--mysql-auth-plugin</b> <i>&lt;plugin&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For MySQL <b>create</b>) Specifies the authentication plugin for new MySQL users (e.g., <i>caching_sha2_password</i>, <i>mysql_native_password</i>). Recommended for enhanced security.<br><br><b><b>--skip-create-database</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For PostgreSQL <b>create</b>) Prevents the automatic creation of a database with the same name as the new user.<br><br><b><b>--with-access</b> <i>&lt;database-name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For PostgreSQL <b>create</b>) Grants the new user access to a specific database. This flag can be used multiple times to grant access to multiple databases.<br><br><b><b>--access</b> <i>&lt;permission-level&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For PostgreSQL <b>create</b>) Sets the permission level for the user on databases they have access to (e.g., <i>read</i>, <i>write</i>, <i>full</i>).<br><br>


title: DESCRIPTION
content:
<i>doctl databases user</i> is a subcommand of the DigitalOcean command-line client (<i>doctl</i>) used for comprehensive management of users within a DigitalOcean Managed Database cluster. It provides a robust interface to perform various essential operations, including creating new database users with specific authentication plugins and access levels, listing all existing users for a given cluster, retrieving detailed information about a particular user, securely deleting users, and resetting user passwords. This command is indispensable for controlling access and permissions to your database clusters programmatically, enabling seamless integration into automation scripts, continuous integration/continuous deployment (CI/CD) pipelines, and Infrastructure as Code (IaC) workflows. It ensures that database user management can be handled efficiently and consistently across your DigitalOcean infrastructure.


title: CAVEATS
content:
Requires a pre-existing DigitalOcean Managed Database cluster. The <i>&lt;cluster-id&gt;</i> argument is mandatory for most operations.<br>The <i>doadmin</i> user, created by default with every cluster, cannot be deleted or have its password reset via <i>doctl databases user</i>.<br>Resetting a password will output the new password to the console; ensure this sensitive information is secured immediately.<br>Deleting a database user is an irreversible action that removes their access to the database cluster. Confirm no critical applications rely solely on that user before deletion.<br>Some database-specific permissions (e.g., granular table permissions or role management) are managed directly within the database client, not via <i>doctl</i>.


title: <B>AUTHENTICATION</B>
content:
To successfully execute <i>doctl databases user</i> commands, you must be authenticated with your DigitalOcean account. This is typically done by running <b>doctl auth init</b> and providing your API token, or by setting the <i>DIGITALOCEAN_ACCESS_TOKEN</i> environment variable.


title: <B>SECURITY BEST PRACTICES</B>
content:
Always create dedicated users for your applications and services instead of using the administrative <i>doadmin</i> user.<br>Grant database users only the necessary permissions (principle of least privilege).<br>For MySQL, utilize strong authentication plugins like <i>caching_sha2_password</i> for enhanced security.<br>Regularly rotate database user passwords, especially for critical applications.<br>Securely store API tokens and generated database user passwords, avoiding hardcoding them in scripts or public repositories.


title: HISTORY
content:
The <i>doctl</i> command-line client, including its extensive support for DigitalOcean's Managed Databases, has evolved significantly since the service's inception. Initially, database management was primarily performed through the DigitalOcean Control Panel. As the demand for automation and programmatic control grew, <i>doctl</i> gained comprehensive capabilities for managing database clusters and their users. This development has been crucial for enabling developers and operations teams to integrate database infrastructure management into CI/CD pipelines and leverage Infrastructure as Code (IaC) principles for their DigitalOcean deployments, making database user management a seamless and automatable process.


title: SYNOPSIS
content:
This man page describes options used with <I>doctl kubernetes</I> subcommands.<br>Usage pattern: <br><I>doctl kubernetes &lt;subcommand&gt; [options]</I><br>To view this document: <br><I>man doctl-kubernetes-options</I>


title: PARAMETERS
content:
<b>--cluster-id</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the unique ID of the Kubernetes cluster.<br><br><b>--cluster-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;References the Kubernetes cluster by its human-readable name.<br><br><b>--format</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output format (e.g., <I>json</I>, <I>yaml</I>, <I>text</I>, <I>csv</I>).<br><br><b>--output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <I>--format</I>.<br><br><b>--no-header</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses column headers in table output.<br><br><b>--kubeconfig</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the Kubernetes configuration file.<br><br><b>--context</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the Kubernetes context to use for the operation.<br><br><b>--region</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the DigitalOcean datacenter region for the cluster (often used with creation/listing).<br><br>


title: DESCRIPTION
content:
The <I>doctl-kubernetes-options</I> document is a man page (manual page) within the DigitalOcean CLI (<I>doctl</I>) that serves as a comprehensive reference for common command-line options available when interacting with DigitalOcean Kubernetes Service (DOKS). It is not an executable command itself, but rather a guide detailing flags and arguments that can be appended to various <I>doctl kubernetes</I> subcommands, such as <I>create</I>, <I>get</I>, <I>list</I>, <I>delete</I>, and <I>kubeconfig</I> operations.<br><br>These options allow users to specify crucial parameters like cluster identifiers, names, output formats, and authentication contexts, streamlining the management of Kubernetes clusters directly from the command line. By providing a centralized overview of these options, <I>doctl-kubernetes-options</I> helps users understand and effectively utilize the full capabilities of <I>doctl</I> for DOKS.


title: CAVEATS
content:
The <I>doctl-kubernetes-options</I> is a reference document, not an executable command itself. <br>The options described within are primarily applicable to commands under the <I>doctl kubernetes</I> family. <br>Not all options are relevant or available for every single <I>doctl kubernetes</I> subcommand; users should refer to the specific subcommand's help output (e.g., <I>doctl kubernetes create --help</I>) for exact applicability.


title: ACCESSING THE DOCUMENT
content:
To view the full <I>doctl-kubernetes-options</I> manual page on a Linux system, use the <I>man</I> command: <br><I>man doctl-kubernetes-options</I>


title: HISTORY
content:
The <I>doctl</I> CLI, including its Kubernetes-related capabilities and associated man pages like <I>doctl-kubernetes-options</I>, has evolved significantly since DigitalOcean introduced its managed Kubernetes service (DOKS). Its development parallels the growth of DOKS, providing comprehensive command-line tooling for managing cluster lifecycle, node pools, and integrations. This specific man page was created to centralize and document the consistent set of options available across various <I>doctl kubernetes</I> operations, improving user experience and documentation.


title: SYNOPSIS
content:
<b>doctl serverless</b> <<i>command</i>> [<i>options</i>]<br><i>Common usage patterns include:</i><br><b>doctl serverless deploy</b> [<i>path</i>] [<i>options</i>]<br><b>doctl serverless functions get</b> <<i>function-name</i>> [<i>options</i>]<br><b>doctl serverless invoke</b> <<i>function-name</i>> [<i>options</i>><br><b>doctl serverless logs</b> <<i>function-name</i>|<i>namespace-name</i>> [<i>options</i>>


title: PARAMETERS
content:
<b>namespaces</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand for managing serverless namespaces. It enables operations like creating, listing, getting details of, and deleting namespaces, which serve as logical groupings for functions.<br><br><b>functions</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand for managing individual serverless functions within a namespace. It provides operations to list, get detailed information about, and delete functions.<br><br><b>triggers</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A subcommand for managing serverless triggers, which define the events that invoke functions (e.g., web requests, cron schedules, or message queues).<br><br><b>deploy</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deploys a serverless project from a local directory to a specified DigitalOcean Functions namespace. This command handles the building, packaging, and uploading of your functions.<br><br><b>invoke</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invokes a deployed function, allowing you to pass an optional payload. It displays the function's response and the activation ID of the execution.<br><br><b>logs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves execution logs for a specific function or an entire namespace, which is crucial for debugging and monitoring the behavior of your serverless applications.<br><br><b>get</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A versatile subcommand used to retrieve detailed information about various serverless resources, commonly used in conjunction with 'functions get' or 'namespaces get'.<br><br><b>delete</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A versatile subcommand used to remove serverless resources, such as specific functions, entire namespaces, or triggers. Often used as 'functions delete' or 'namespaces delete'.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks the deployment status of a serverless project within a namespace, indicating if the deployment is pending, complete, or has encountered errors.<br><br>


title: DESCRIPTION
content:
The <b>doctl-serverless</b> command is a powerful plugin for the DigitalOcean CLI (<b>doctl</b>) specifically designed for interacting with and managing DigitalOcean Functions (serverless) deployments. It provides a comprehensive set of tools to streamline the entire serverless development lifecycle directly from the command line, enabling developers to efficiently manage their serverless applications. Users can leverage <b>doctl-serverless</b> to perform critical operations such as deploying function code from local project directories to specified namespaces, listing and retrieving detailed information about existing functions and namespaces, and managing triggers that automate function execution. Furthermore, it facilitates real-time interaction by allowing users to invoke deployed functions with custom payloads and retrieve execution logs for debugging and monitoring. This command significantly simplifies the workflow for developers building and operating serverless applications on the DigitalOcean platform, offering granular control over deployments, resource management, and providing real-time insights into function performance and status.


title: CAVEATS
content:
The <b>doctl-serverless</b> command is implemented as a plugin and therefore requires the main <b>doctl</b> CLI tool to be installed and properly configured with a DigitalOcean API token. It is exclusively designed for the DigitalOcean Functions serverless platform and relies on a specific project directory structure, typically defined by a <i>project.yml</i> file, for successful deployments.


title: INSTALLATION
content:
The <b>doctl-serverless</b> plugin is often bundled with recent installations of the <b>doctl</b> CLI. If not present or to ensure you have the latest version, it can be easily installed or updated using the command: <b>doctl plugin install serverless</b> or <b>doctl plugin update serverless</b>.


title: PROJECT CONFIGURATION
content:
For deploying functions, <b>doctl-serverless</b> expects a specific project structure within your local directory. This typically includes a <i>project.yml</i> file at the root, which defines namespaces, functions, routes, and associated settings, guiding the deployment process and ensuring proper resource provisioning on DigitalOcean.


title: HISTORY
content:
DigitalOcean Functions, the serverless platform managed by this command, was introduced in beta around late 2021 and became generally available in early 2022. The <b>doctl-serverless</b> plugin was developed concurrently to provide a robust command-line interface for developers to build, deploy, and manage their serverless applications. Its ongoing development focuses on integrating seamlessly with the broader DigitalOcean ecosystem and continually simplifying the serverless workflow, with new features added as the Functions platform evolves.


title: SYNOPSIS
content:
As <b><i>doctum</i></b> is not a recognized standard Linux command, a universal synopsis does not exist. If it were a custom script or alias, its usage would depend entirely on its implementation and defined arguments.


title: DESCRIPTION
content:
The command <b><i>doctum</i></b> is not recognized as a standard or commonly available utility in mainstream Linux distributions like Debian, Ubuntu, Fedora, or RHEL. A comprehensive search of official man pages, package repositories, and common Linux command-line tools reveals no documented entry for a command with this exact name performing a system-level function. <br><br>It is highly probable that 'doctum' refers to a highly specific, niche application, a custom script developed for a particular environment, an alias defined within a user's or system's shell configuration (e.g., in <i>~/.bashrc</i> or <i>/etc/profile</i>), or it could potentially be a typographical error for another, more common command. Without additional context regarding its origin or the specific system it is being referenced on, its functionality, purpose, or usage cannot be precisely determined based on the standard set of Linux commands. Users encountering `doctum` should first check their shell history, aliases (`alias doctum`), environment `PATH` for local executables, or specific project documentation within their operating context. Its meaning is literally 'learned' or 'taught' in Latin, which offers no direct clue to a command-line utility.


title: CAVEATS
content:
The primary caveat is that <b><i>doctum</i></b> is not a recognized standard Linux command, meaning its presence or functionality cannot be assumed across different systems. Its behavior, if it exists, would be entirely dependent on its local implementation, making it non-portable and undocumented in general contexts. Users should exercise caution and investigate its source if they encounter it.


title: POTENTIAL EXPLANATIONS
content:
If you encountered 'doctum', consider the following possibilities:<br>1. It's a typo for a known command (e.g., <i>'dictum'</i> in some very old, obscure contexts, or another command entirely).<br>2. It's a custom script or program installed locally on your system or within a specific project directory, perhaps added to your `PATH`.<br>3. It's a shell alias defined in your shell's configuration files (e.g., <i>~/.bashrc</i>, <i>~/.zshrc</i>). You can check with `alias doctum`.<br>4. It's part of a very specialized or deprecated software package not widely used today.<br>5. It refers to a non-command concept (e.g., a project name like 'Doctum' for PHP documentation).


title: HISTORY
content:
There is no documented history for <b><i>doctum</i></b> as a standard Linux command, as it does not appear in historical or current Linux utility collections. Any 'history' would pertain to a specific, localized implementation within a particular project or system, not a general utility used across Linux environments.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints version information.<br><br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses printing of the question section in the output.<br><br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the full DNS packet, including raw header details.<br><br><br><b><b>-J</b>, <b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats the DNS answer output as JSON, suitable for programmatic parsing.<br><br><br><b><b>-C</b>, <b>--color</b> <i><WHEN></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls when to colorize the output. Options include 'auto' (default), 'always', or 'never'.<br><br><br><b><b>-1</b>, <b>--short</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the first answer in a concise format.<br><br><br><b><b>-Q</b>, <b>--question</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly prints the question section of the DNS query.<br><br><br><b><b>-A</b>, <b>--answer</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly prints the answer section of the DNS response.<br><br><br><b><b>-N</b>, <b>--authority</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly prints the authority section of the DNS response.<br><br><br><b><b>-E</b>, <b>--additional</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly prints the additional section of the DNS response.<br><br><br><b><b>-Z</b>, <b>--no-id</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not print the DNS message ID, useful for scripting.<br><br><br><b><b>-U</b>, <b>--udp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces DNS queries over UDP (Do53). This is often the default.<br><br><br><b><b>-T</b>, <b>--tcp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces DNS queries over TCP (Do53), useful for larger responses.<br><br><br><b><b>-S</b>, <b>--tls</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses DNS-over-TLS (DoT) for encrypted DNS queries.<br><br><br><b><b>-H</b>, <b>--https</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses DNS-over-HTTPS (DoH) for encrypted DNS queries.<br><br><br><b><b>-L</b>, <b>--locate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Locates DNS servers by querying the root servers, providing a server list.<br><br><br><b><b>-D</b>, <b>--dnssec</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables DNSSEC checking and displays DNSSEC-related records (RRSIG, NSEC, etc.).<br><br><br><b><b>-t</b> <i><TYPE></i>, <b>--type</b> <i><TYPE></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the type of DNS record to look up (e.g., A, AAAA, MX, TXT, CNAME, ANY).<br><br><br><b><b>-s</b> <i><SERVER></i>, <b>--server</b> <i><SERVER></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the DNS server to query. Can be an IP address or hostname. Alias for <i>@SERVER</i>.<br><br><br><b><b>-p</b> <i><PORT></i>, <b>--port</b> <i><PORT></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number to use for DNS queries. Defaults to 53 for Do53, 853 for DoT, 443 for DoH.<br><br><br><b><b>--timeout</b> <i><DURATION></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum time to wait for a DNS response (e.g., 2s, 500ms).<br><br><br><b><b>--retries</b> <i><COUNT></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of times to retry a query if it fails.<br><br><br><b><b>--edns</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables EDNS (Extension Mechanisms for DNS), which allows for larger DNS messages.<br><br><br><b><b>--class</b> <i><CLASS></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the DNS class for the query (e.g., IN for Internet, CH for Chaos).<br><br><br><b><b>--check</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verifies that the server can resolve the given name, reporting success or failure.<br><br><br><b><b>--homenet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses DNS servers configured in the system's <b>resolv.conf</b> for home network lookups.<br><br><br>


title: DESCRIPTION
content:
<b>dog</b> (sometimes referred to as <b>doggo</b>) is a modern, open-source command-line DNS client written in Rust. It serves as an intuitive alternative to traditional DNS lookup tools like <b>dig</b> or <b>nslookup</b>, aiming to provide a more user-friendly experience with clear, colorized output by default.<br><br><b>dog</b> supports a wide range of DNS record types and features, including DNS-over-TLS (DoT), DNS-over-HTTPS (DoH), and traditional DNS-over-UDP/TCP (Do53). It also offers options for JSON output, concise short-form output, and detailed query introspection, making it a versatile tool for network troubleshooting, development, and general DNS queries. Its design prioritizes readability and ease of use, making complex DNS lookups more accessible to a broader audience.


title: CAVEATS
content:
<ul><li><b>Not a Default Command:</b> <b>dog</b> is not typically pre-installed on most Linux distributions and needs to be installed separately, unlike <b>dig</b> or <b>host</b>.<br></li><li><b>Active Development:</b> As a relatively new and actively developed tool, its features, options, and output format may evolve with new versions, potentially leading to minor inconsistencies between different installed versions.<br></li><li><b>Dependencies:</b> While Rust-based, its installation might require Rust's toolchain or pre-built binaries specific to your architecture.</li></ul>


title: RUST IMPLEMENTATION
content:
<b>dog</b> is written entirely in Rust, which contributes to its reputation for speed, reliability, and security. Rust's memory safety guarantees help prevent common programming errors, making <b>dog</b> a robust tool for critical network diagnostics.<br>


title: MODERN PROTOCOLS SUPPORT
content:
A key advantage of <b>dog</b> is its native support for modern, encrypted DNS protocols like DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH). These protocols provide a layer of encryption for DNS queries, significantly enhancing user privacy and security by preventing eavesdropping and manipulation of DNS traffic.<br>


title: USER-FRIENDLY EXPERIENCE
content:
Designed with a strong focus on readability and ease of use, <b>dog</b> provides colorized output by default, making it easier to distinguish different parts of a DNS response. Its options for structured JSON output also facilitate integration into scripts and automated workflows, simplifying data parsing and analysis.


title: HISTORY
content:
<b>dog</b> was initiated by a community of developers in 2018, aiming to create a modern, more user-friendly command-line DNS client as an alternative to the long-standing, often complex <b>dig</b> utility. Leveraging the Rust programming language, its development focused on performance, memory safety, and concurrency, alongside a strong emphasis on user experience through features like colorized output and native support for contemporary DNS protocols. Its creation addressed the growing need for easily accessible tools capable of performing DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH) queries, which are crucial for enhancing privacy and security in current internet environments. Since its inception, <b>dog</b> has steadily gained traction among network administrators and developers seeking a more ergonomic and powerful tool for their DNS troubleshooting and querying needs.


title: PARAMETERS
content:
<b><b>-b</b>, <b>--bark</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a playful barking sound or 'bork' message.<br><br><b><b>-p</b>, <b>--pupper</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a random ASCII art representation of a dog or puppy.<br><br><b><b>-m</b>, <b>--message</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Presents a random dog-themed quote or wholesome message.<br><br><b><b>-l</b>, <b>--lick</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulates a dog lick by displaying a friendly text output.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the command's help message and exits.<br><br>


title: DESCRIPTION
content:
The <b>doggo</b> command is <i>not</i> a standard utility found in most Linux distributions. Instead, it typically refers to a custom, user-created script or a meme-inspired program designed to output whimsical, dog-related content to the terminal. This often includes ASCII art representations of dogs, humorous dog quotes, or various "barking" sounds represented textually. Its purpose is primarily for entertainment and lighthearted fun, often shared among users who appreciate internet dog memes. Implementations vary widely, frequently leveraging existing tools like <b>cowsay</b>, <b>fortune</b>, or simple <b>echo</b> commands combined with text files containing dog-themed data. Users usually install it by downloading or creating a script and placing it in their PATH.


title: CAVEATS
content:
<b>doggo</b> is not a standard Linux command and must be manually installed or created by the user. Its functionality and available options can vary significantly depending on the specific script implementation found or written by the user. Users should exercise caution when installing custom scripts from untrusted sources.


title: COMMON IMPLEMENTATIONS
content:
Common ways to implement <b>doggo</b> include:<br><i>Shell Scripts:</i> Simple scripts using <b>echo</b> to print pre-defined ASCII art or messages.<br><i>Cowsay/Fortune Integration:</i> Using <b>cowsay</b> with a custom dogfile (a <b>cowsay</b> equivalent for dogs) or piping <b>fortune</b> output into <b>cowsay</b> with a dog character.<br><i>Python/Perl Scripts:</i> More complex versions might use scripting languages to fetch random dog facts from APIs or generate more dynamic output.


title: HISTORY
content:
The concept of <b>doggo</b> as a Linux command arose from the popular "doggo" internet meme, which celebrates dogs in various adorable and humorous contexts. As a result, users began creating simple scripts, primarily for personal amusement or to share with friends, to bring this meme-inspired joy to the command line. Its "development" is decentralized, with many independent implementations rather not a single official project. It embodies the playful, creative spirit of the Linux community.


title: SYNOPSIS
content:
<b>dokku</b> <i>&lt;command&gt;</i> [<i>&lt;args&gt;</i>]<br><br>Examples:<br><b>dokku</b> <i>apps:list</i><br><b>dokku</b> <i>config:set myapp DATABASE_URL=...</i><br><b>dokku</b> <i>logs myapp -t</i>


title: PARAMETERS
content:
<b><i>apps:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages applications (e.g., create, destroy, list).<br><br><b><i>config:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages environment variables for applications.<br><br><b><i>logs &lt;app&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays application logs.<br><br><b><i>ps:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages application processes (e.g., scale, restart, stop).<br><br><b><i>repo:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages Git repositories for applications.<br><br><b><i>plugins:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages Dokku plugins (e.g., install, list).<br><br><b><i>network:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures container networking for applications.<br><br><b><i>storage:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages persistent storage for applications.<br><br><b><i>domains:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages custom domains for applications.<br><br><b><i>ssl:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages SSL certificates for applications.<br><br><b><i>proxy:&lt;subcommand&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures application proxy settings.<br><br>


title: DESCRIPTION
content:
<i>dokku</i> is an open-source Platform as a Service (PaaS) that helps developers deploy and manage applications on a single server. Often referred to as a 'mini-Heroku', it leverages <B>Docker</B> to containerize applications and <B>Git</B> for deployments.<br><br>When an application's code is pushed to the <i>dokku</i> server via Git, <i>dokku</i> automatically detects the application's language or framework (using buildpacks, similar to Heroku, or by detecting a <i>Dockerfile</i>), builds it into a Docker image, and then runs it as a container. It simplifies the deployment workflow by abstracting away much of the underlying infrastructure management, allowing developers to focus on their code. It's ideal for small to medium-sized projects, personal applications, or internal tools where the simplicity of a PaaS is desired without the cost or vendor lock-in of a cloud provider.


title: CAVEATS
content:
<i>dokku</i> is designed for single-server deployments, meaning it doesn't offer built-in high availability or clustering capabilities. While powerful for its niche, it requires some Linux server administration knowledge for initial setup and maintenance. Debugging deployment issues can sometimes be challenging, especially when dealing with complex buildpack interactions or Dockerfile specifics. It's not a direct replacement for large-scale, distributed PaaS solutions.


title: EXTENSIBLE PLUGIN ARCHITECTURE
content:
A significant feature of <i>dokku</i> is its extensive plugin system. This allows users to add functionalities like database services (e.g., PostgreSQL, MySQL, Redis), persistent storage, specific proxy configurations, and more, extending the core capabilities of the platform. Plugins are often community-contributed and can be easily installed and managed via the <b>dokku plugins</b> commands.


title: BUILDPACK AND DOCKERFILE SUPPORT
content:
<i>dokku</i> offers flexibility in how applications are built. It supports Heroku-compatible buildpacks, which automatically detect and build applications based on their language and framework. Alternatively, users can provide a custom <i>Dockerfile</i> in their repository, giving them granular control over the build process and the resulting Docker image.


title: HISTORY
content:
<i>dokku</i> was initially created by Jeff Lindsay in 2013, aiming to provide a lightweight, self-hostable alternative to cloud-based PaaS offerings like Heroku. Its development closely followed the rise of <B>Docker</B>, utilizing Docker containers as its core deployment unit. Over the years, it has evolved into a robust and extensible platform, driven by a dedicated community, maintaining its focus on simplicity and ease of use for single-server application deployments. Its plugin architecture has allowed it to grow beyond basic application deployment to include database services, persistent storage, and more.


title: PARAMETERS
content:
<b><i>URL...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more file paths or directory URLs to open. For example, <b>dolphin ~/Documents</b> or <b>dolphin /var/log</b>.<br><br><b><b>--new-window</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the specified URLs in a new <b>Dolphin</b> window, regardless of whether another <b>Dolphin</b> instance is already running.<br><br><b><b>--select &lt;URL&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the parent directory of <i>&lt;URL&gt;</i> and selects the specified file or folder within that directory. For example, <b>dolphin --select ~/Documents/report.pdf</b>.<br><br><b><b>--show-places</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the <i>Places</i> panel (navigation pane) is visible upon opening the <b>Dolphin</b> window.<br><br><b><b>--hide-places</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the <i>Places</i> panel (navigation pane) is hidden upon opening the <b>Dolphin</b> window.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <b>Dolphin</b> version information and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of general command-line options for <b>Dolphin</b> and exits.<br><br>


title: DESCRIPTION
content:
<b>Dolphin</b> is the default file manager for the <i>KDE Plasma</i> desktop environment. It is designed to be user-friendly while offering robust features for navigating, organizing, and managing files and folders.<br><br>Key capabilities include <i>tabbed browsing</i>, <i>split views</i>, multiple view modes (icons, details, columns), an <i>integrated terminal panel</i>, a customizable toolbar, and comprehensive network browsing support (FTP, SFTP, Samba, WebDAV). Dolphin supports plugins for extended functionality and is known for its speed and flexibility. It aims to provide a pleasant and efficient file management experience, making it easy to perform common operations like copying, moving, deleting, and renaming files, as well as more advanced tasks.


title: CAVEATS
content:
<b>Dolphin</b> is primarily a graphical application; its command-line usage is mainly for opening specific paths or controlling the initial state of its graphical window. It requires the <i>KDE Plasma</i> desktop environment or at least the <i>Qt libraries</i> to run. It is not designed for non-interactive scripting or command-line file manipulation tasks, for which traditional CLI tools like <b>ls</b>, <b>cp</b>, <b>mv</b>, <b>rm</b> are more appropriate.


title: INTEGRATION WITH KDE PLASMA
content:
<b>Dolphin</b> is deeply integrated with the <i>KDE Plasma</i> desktop environment, leveraging <i>KDE Frameworks</i> for core functionalities. This includes <i>KIO</i> (KDE Input/Output) for network transparency, allowing seamless access to remote file systems (FTP, SFTP, Samba, WebDAV) as if they were local files, and <i>KWallet</i> for secure password management.


title: EXTENSIBILITY
content:
<b>Dolphin</b> supports various plugins and service menus that extend its capabilities. These can include integration with version control systems (like Git or Subversion), enhanced image previews, file checksum tools, and custom actions accessible via the context menu.


title: HISTORY
content:
<b>Dolphin</b> was first released in 2006 as part of <i>KDE 4.0</i>. Its development aimed to provide a dedicated, lightweight, and modern file manager for <i>KDE</i>, separating its functionality from <b>Konqueror</b>, which previously served as both a web browser and a file manager. This separation allowed <b>Dolphin</b> to be optimized purely for file management, leading to improved usability and performance. It quickly became and remains the default <i>KDE</i> file manager due to its intuitive interface and robust feature set.


title: SYNOPSIS
content:
<b>dolt</b> [<I>GLOBAL_OPTIONS</I>] <I>COMMAND</I> [<I>COMMAND_OPTIONS</I>] [<I>ARGS</I>]<br><br>Dolt operations are performed using subcommands, similar to Git. Common invocations include:<br><b>dolt clone</b> <I>repository_url</I><br><b>dolt add</b> <I>table_name</I><br><b>dolt commit</b> -m "<I>message</I>"<br><b>dolt diff</b> <I>table_name</I><br><b>dolt sql</b> -q "<I>SELECT * FROM my_table</I>"


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for the command or subcommand.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress most output from Dolt.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about operations.<br><br><b>--config <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specific configuration file instead of the default.<br><br><b>--dir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the working directory for Dolt operations.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug logging for detailed internal operation visibility.<br><br>


title: DESCRIPTION
content:
Dolt is a SQL database that supports Git-like version control capabilities. It allows users to <b>clone</b>, <b>branch</b>, <b>merge</b>, <b>push</b>, and <b>pull</b> data just like source code. This brings powerful collaboration and auditing features to datasets, enabling data engineers, analysts, and developers to manage data with the same rigorous version control practices applied to software development.<br><br>It provides a command-line interface highly inspired by Git, as well as a MySQL-compatible server mode for standard SQL operations. Dolt fundamentally changes how data can be managed, providing a complete history of every change to your database and enabling reversible operations and conflict resolution for data.


title: CAVEATS
content:
Dolt is optimized for data versioning and collaboration rather than high-volume transactional workloads typical of traditional OLTP databases. While it offers MySQL compatibility, its performance characteristics may differ for extremely large datasets or complex analytical queries. Its storage model, while powerful for diffing and merging, can lead to higher disk space usage due to maintaining a complete history of changes. The ecosystem and tool integrations are still maturing compared to decades-old relational database systems.


title: CORE CONCEPTS
content:
Dolt operates on several key concepts borrowed from Git, including:<br><b>Working Set</b>: The current state of your data that you are actively modifying.<br><b>Staging Area (Index)</b>: An intermediate area where you prepare changes before committing them.<br><b>Commit Graph</b>: A historical record of all changes, represented as a directed acyclic graph (DAG) of commits.<br><b>Branches</b>: Pointers to specific commits, allowing for parallel lines of development or experimentation with data.<br><b>Remotes</b>: Remote repositories (e.g., on DoltHub or a private server) that enable collaboration and data sharing.


title: COMMON USE CASES
content:
Dolt is particularly useful for:<br><b>Data Auditing</b>: Easily track every change made to your data, who made it, and when.<br><b>Collaborative Data Analysis</b>: Data scientists and analysts can work on shared datasets, branch off for experiments, and merge changes back.<br><b>Reproducible Research</b>: Ensure that data used for analysis or experiments can be precisely reproduced at any point in time.<br><b>Data Migration and Rollback</b>: Manage database schema and data changes with the ability to easily revert to previous states or branch for testing migrations.<br><b>Data Sharing</b>: Distribute datasets with their full history, enabling others to clone and contribute.


title: HISTORY
content:
Dolt was developed by DoltHub, a company co-founded by Zachery Anderson and Timothy Sehn, with the goal of applying Git-like version control principles to SQL databases. The project was first publicly released in 2019. It was designed from the ground up to provide a robust solution for data versioning, branching, and merging, addressing common challenges faced by data professionals in managing evolving datasets.


title: PARAMETERS
content:
<b><I>pathspec</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more table names or path specifications to stage. Only changes to these tables will be added to the staging area.<br><br><b>--all, -A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stages all changes in the working directory, including new tables, modified tables, and deleted tables.<br><br><b>--force, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows adding files that have merge conflicts. This option forces them into the staging area with conflict markers, requiring manual resolution before committing.<br><br>


title: DESCRIPTION
content:
dolt add is a fundamental command in <b>Dolt</b>, the <I>version-controlled SQL database</I>.<br><br>Similar to `git add`, it prepares changes from the working directory to be included in the next Dolt commit. These changes can include modifications to existing tables, the addition of new tables, or deletions. Users specify which changes to stage using <I>pathspec</I> (e.g., table names) or stage all changes with the `--all` option.<br><br>Staging is a crucial intermediate step, allowing users to carefully select and group related changes before permanently recording them in the Dolt history using `dolt commit`. It ensures that only intended modifications are part of a snapshot, providing granular control over database versioning.


title: CAVEATS
content:
Staging changes with `dolt add` does <B>not</B> permanently save them; a subsequent `dolt commit` is required to record the changes in the database history.<br><br>Using `--all` will stage <B>all</B> untracked, modified, and deleted items, so exercise caution to avoid staging unintended changes. Be aware that tables with unresolved merge conflicts require the `--force` option to be added.


title: THE STAGING AREA
content:
In Dolt, the <I>staging area</I> (also known as the index) is a temporary buffer where you collect changes from your working directory before committing them. `dolt add` moves changes into this area, allowing you to curate a snapshot of your database to be committed.


title: DATA VS. FILE STAGING
content:
Unlike traditional Git which primarily stages file changes, `dolt add` is designed to stage changes to <b>table schemas</b> and <b>table data</b>. While it can also operate on SQL files or other tracked files, its primary power lies in managing granular database modifications.


title: HISTORY
content:
The `dolt add` command has been a core component of the Dolt version control system since its public release by DoltHub in 2019. Its design directly mirrors the `git add` command, bringing the familiar concept of a <I>staging area</I> to relational databases. This allows users to prepare specific sets of schema and data modifications for atomic commits, a fundamental workflow for versioning data effectively.


title: SYNOPSIS
content:
<b>dolt blame</b> [<i>&lt;options&gt;</i>] [<i>&lt;ref-spec&gt;</i>] [<i>&lt;path-or-table&gt;</i>...]


title: PARAMETERS
content:
<b><i>&lt;ref-spec&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the commit to blame from (e.g., <b>HEAD~1</b>, <b>main</b>, <b>v1.0</b>). If omitted, blames the current <b>HEAD</b>.<br><br><b><i>&lt;path-or-table&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific table name or file path to blame. This can be a table name like '<b>mytable</b>' or a file path like '<b>data/file.csv</b>'.<br><br><b><b>-L</b> <i>&lt;start&gt;</i>,<i>&lt;end&gt;</i> or <b>--line-range=</b><i>&lt;start&gt;</i>,<i>&lt;end&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only a specific range of lines. For tables, this refers to row numbers.<br><br><b><b>--porcelain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in a machine-readable format, suitable for scripting.<br><br><b><b>--working</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blame the version of the file or table as it exists in the working directory (uncommitted changes).<br><br><b><b>--cached</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blame the version of the file or table as it exists in the staged (cached) area.<br><br><b><b>--no-contents</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress showing the actual line contents in the output, only displaying commit and author information.<br><br><b><b>--ignore-rev</b> <i>&lt;rev&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore changes made by a specific commit hash when tracing history. Useful for excluding formatting-only commits.<br><br><b><b>--ignore-revs-file</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore changes made by commits listed one per line in the specified file.<br><br>


title: DESCRIPTION
content:
<i>dolt blame</i> is a command in <I>Dolt</I>, a SQL database with Git-like version control features. Similar to <i>git blame</i>, it displays the author and commit information for every line of a specified table or file. This is invaluable for understanding the history of data changes, identifying who last modified a particular row or schema element, and when. It operates on the <I>Dolt</I> repository's history, allowing users to trace data lineage back to its origin. The command supports various options to refine the output, such as focusing on specific line ranges, ignoring certain revisions, or displaying information in a machine-readable format. It's a crucial tool for auditing data changes and collaborating on data-driven projects in a version-controlled environment.


title: CAVEATS
content:
Unlike <i>git blame</i> which primarily operates on text files, <i>dolt blame</i> applies to table data, which can be more complex due to schema changes and data types. Interpreting blame on schema changes might require understanding Dolt's internal representation of schema. Blaming very large tables or an extensive history can be resource-intensive and time-consuming.


title: DATA VS. SCHEMA BLAME
content:
<i>dolt blame</i> can be used to trace changes to both the table's data rows and its schema definition (e.g., column additions/deletions). The output will adapt to show the relevant history for each type of change.


title: PRIMARY KEY IMPORTANCE
content:
In <I>Dolt</I>, primary keys are fundamental for identifying rows across versions. This is crucial for <i>dolt blame</i> to correctly track the lineage of individual data rows, even if their non-key values change over time.


title: HISTORY
content:
<I>Dolt</I> is a SQL database built on Git principles, developed by DoltHub (now DoltHub, Inc.). It was first introduced around 2018-2019, aiming to bring the benefits of Git-like version control (branching, merging, diffing, blame) to structured data. <i>dolt blame</i> was a natural inclusion, mirroring the popular <i>git blame</i> command, but adapted to operate on SQL tables and schema. Its development reflects the broader trend of applying version control paradigms to data management, moving beyond traditional code repositories.


title: SYNOPSIS
content:
<b>dolt branch</b> [<I>options</I>]<br><b>dolt branch</b> [<I>branchname</I> [<I>start-point</I>]]<br><b>dolt branch</b> [<b>--set-upstream-to</b> | <b>-u</b>] <I>upstream</I> [<I>branchname</I>]<br><b>dolt branch</b> [<b>--track</b> | <b>-t</b>] <I>remote</I>/<I>branchname</I><br><b>dolt branch</b> [<b>--unset-upstream</b> | <b>-u</b>] [<I>branchname</I>]<br><b>dolt branch</b> [<b>--delete</b> | <b>-d</b> | <b>--force-delete</b> | <b>-D</b>] <I>branchname</I>...<br><b>dolt branch</b> [<b>--move</b> | <b>-m</b> | <b>--copy</b> | <b>-c</b>] [<I>oldbranch</I>] <I>newbranch</I>


title: PARAMETERS
content:
<b><i>branchname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the branch to create, delete, or operate on.<br><br><b><i>start-point</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The commit, branch, or tag from which to start the new branch. Defaults to the current HEAD.<br><br><b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List existing branches. This is the default if no branch name is provided.<br><br><b><b>-v</b>, <b>-vv</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be more verbose when listing branches, showing the last commit SHA and subject.<br><br><b><b>-r</b>, <b>--remotes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List remote-tracking branches.<br><br><b><b>--all</b>, <b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List both local and remote-tracking branches.<br><br><b><b>--delete</b>, <b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete a branch only if it has been fully merged into its upstream, or HEAD.<br><br><b><b>--force-delete</b>, <b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force delete a branch, regardless of its merged status. Alias for <b>--delete --force</b>.<br><br><b><b>--move</b>, <b>-m</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Move or rename a branch.<br><br><b><b>--copy</b>, <b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copy a branch.<br><br><b><b>--set-upstream-to</b>, <b>-u</b> <I>upstream</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the upstream branch for the current branch or the specified branch. This configures tracking.<br><br><b><b>--track</b>, <b>-t</b> <I>remote</I>/<I>branchname</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new branch that tracks a remote branch. Equivalent to <b>dolt checkout -b <newbranch> --track <remote>/<branchname></b>.<br><br><b><b>--unset-upstream</b>, <b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the upstream information for the current branch or the specified branch.<br><br><b><b>--force</b>, <b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the creation of a branch, even if it already exists or if it would overwrite an existing branch.<br><br><b><b>--show-current</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the name of the current branch.<br><br>


title: DESCRIPTION
content:
<i>dolt-branch</i> is a subcommand of <i>dolt</i>, a unique SQL database that natively supports Git-like version control features. It allows users to create, list, delete, and rename branches within a Dolt repository. Similar to Git, branches in Dolt represent independent lines of development, but instead of tracking changes to files, they track changes to the entire database state, including schema and data.<br><br>This command is fundamental for collaborative data management, enabling multiple users or processes to work on different versions of a database concurrently without affecting the main line of development. It facilitates experimental changes, feature development, and bug fixes on isolated database states, which can later be merged back into other branches, providing a powerful workflow for data evolution.


title: CAVEATS
content:
<i>dolt-branch</i> is a subcommand of the <i>dolt</i> version control system for data and is not a standalone Linux command. It requires Dolt to be installed and initialized in a directory as a Dolt repository. Unlike traditional Git, <i>dolt-branch</i> manages branches of database states, including schema and data, rather than file system snapshots. Users familiar with Git's branching model will find strong conceptual similarities, but the underlying data management and potential conflicts (e.g., schema merges) are distinct and SQL-centric.


title: BRANCHING IN DOLT VS. GIT
content:
While <i>dolt-branch</i> behaves conceptually like <i>git-branch</i>, it's crucial to understand the distinction in what they version. Git branches track versions of a filesystem hierarchy (files and directories). Dolt branches, conversely, track versions of a SQL database's state, including its schema (tables, columns, types) and its data (rows within tables). This allows for operations like merging different database schemas or data sets, resolving conflicts at the SQL level, and reverting database states to previous versions, all managed with the familiar branching workflow.


title: HISTORY
content:
Dolt, and by extension <i>dolt-branch</i>, emerged from the critical need for robust version control for relational databases, a capability traditionally lacking in standard database systems. Developed by Liquidata (now DoltHub), Dolt builds upon the foundational ideas of Noms, a distributed versioned data store. <i>dolt-branch</i> was designed to mirror the powerful and familiar branching paradigm of Git, adapting it to the specific challenges of managing evolving database schemas and data. Its development has focused on providing a familiar user experience for developers accustomed to code version control, extending those benefits to the database layer and enabling Git-like workflows for data management.


title: SEE ALSO
content:
dolt(1), dolt-checkout(1), dolt-merge(1), dolt-commit(1), git-branch(1) <I>(conceptual similarity)</I>


title: SYNOPSIS
content:
<b>dolt clone</b> [<i>&lt;options&gt;</i>] <i>&lt;repository_url&gt;</i> [<i>&lt;destination_path&gt;</i>]


title: PARAMETERS
content:
<b><i>&lt;repository_url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The URL of the remote Dolt repository to clone. This can be a DoltHub URL (e.g., <i>dolthub/organization/repository</i>), an HTTP(S) URL, or an SSH URL.<br><br><b>[<i>&lt;destination_path&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional path to the directory where the cloned repository will be placed. If omitted, the repository will be cloned into a new directory named after the repository component of the URL.<br><br><b><b>--branch</b> <i>&lt;branch_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check out <i>&lt;branch_name&gt;</i> instead of the remote's default branch after cloning the repository.<br><br><b><b>--config</b> <i>&lt;key&gt;</i>=<i>&lt;value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a configuration variable in the newly created repository's local configuration.<br><br><b><b>--depth</b> <i>&lt;depth&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a shallow clone with a history truncated to the specified number of commits from the head of the chosen branch.<br><br><b><b>--no-checkout</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clone the repository but do not check out a working tree. This leaves the working directory empty, containing only the <i>.dolt</i> directory.<br><br><b><b>--bare</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a bare Dolt repository. A bare repository does not have a working directory for SQL operations but contains only the <i>.dolt</i> directory, suitable for serving as a remote.<br><br><b><b>--origin</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign the name <i>&lt;name&gt;</i> to the remote tracking the cloned repository instead of the default <i>origin</i>.<br><br>


title: DESCRIPTION
content:
<i>dolt-clone</i> is a core command within the Dolt database system, which uniquely combines a SQL database with Git-like version control features. It functions analogously to <i>git clone</i>, allowing users to create a local copy of a remote Dolt repository. When <i>dolt-clone</i> is executed, it fetches all the commits and their associated database states from the specified remote URL and checks out the default branch (typically <i>main</i> or <i>master</i>) into a new directory. This directory becomes a fully functional local Dolt repository, enabling users to interact with the database, make changes, commit them, and push/pull from remotes, just like with Git. It is the primary way to begin working with an existing Dolt database hosted remotely, for instance, on DoltHub or a self-hosted Dolt server. The cloned directory will contain the Dolt internal data files (the <i>.dolt</i> directory) and a working SQL database instance ready for interaction.


title: CAVEATS
content:
<b>Large Repositories:</b> Cloning very large Dolt repositories, especially those with extensive history or massive datasets, can be time-consuming and resource-intensive, requiring significant network bandwidth and disk I/O.<br><br><b>Authentication:</b> Accessing private Dolt repositories requires proper authentication, typically via SSH keys configured on the system or through <i>dolt login</i> for DoltHub credentials.<br><br><b>Disk Space:</b> A full clone requires disk space equivalent to the entire historical data of the database, as all past commits and their states are downloaded.<br><br><b>Network Dependency:</b> The performance and success of the clone operation are highly dependent on network speed, latency, and the responsiveness of the remote Dolt server.


title: SUPPORTED PROTOCOLS
content:
<i>dolt-clone</i> supports various protocols for accessing remote repositories, including the native <i>dolt</i> protocol (often used for DoltHub and self-hosted Dolt servers), standard <i>HTTP(S)</i>, and <i>SSH</i>. The protocol used typically determines the format of the <i>&lt;repository_url&gt;</i>.


title: DEFAULT BRANCH AND WORKING DIRECTORY
content:
By default, upon successful cloning, <i>dolt-clone</i> checks out the remote's default branch (commonly <i>main</i> or <i>master</i>) into a new directory. This directory, named after the repository (or the specified <i>&lt;destination_path&gt;</i>), becomes the working directory containing both the <i>.dolt</i> internal data directory and the current state of the database.


title: HISTORY
content:
Dolt, developed by Liquidata (now DoltHub), was publicly launched in 2019 with the vision of applying Git-like version control to SQL databases. From its inception, <i>dolt-clone</i> has been a fundamental command, mirroring the indispensable role of <i>git clone</i> in the Git ecosystem. It was designed to provide users with an intuitive and familiar way to acquire and begin interacting with existing Dolt databases, thereby facilitating collaboration and the distribution of versioned data. Its command-line interface and option set were consciously designed to parallel <i>git clone</i>, ensuring a smooth transition and familiar experience for developers already proficient with Git workflows.


title: PARAMETERS
content:
<b><b>-m</b> <I>&lt;msg&gt;</I>, <b>--message</b> <I>&lt;msg&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified <I>&lt;msg&gt;</I> as the commit message. Multiple <I>-m</I> options can be provided; their messages will be concatenated.<br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically stages all modified and deleted tables before committing. This bypasses the need to run <i>dolt add</i> manually for these changes.<br><br><b><b>--amend</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used to modify the most recent commit. This operation rewrites history by replacing the last commit with a new one that includes any currently staged changes and the original (or a new) commit message.<br><br><b><b>--author</b> <I>&lt;author&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides the commit author. The format should be "Author Name &lt;email@example.com&gt;".<br><br><b><b>--date</b> <I>&lt;date&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides the commit date. This can be specified in various formats, such as an RFC 2822 date or a UNIX timestamp.<br><br><b><b>--allow-empty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Permits creating a commit even if there are no changes staged. This is useful for marking a specific state or for creating a starting point in an empty repository.<br><br><b><b>--no-edit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the provided commit message (e.g., with <i>-m</i> or <i>--file</i>) without launching an external editor.<br><br><b><b>--file</b> <I>&lt;file&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Takes the commit message from the specified file instead of opening an editor or using <i>-m</i>.<br><br><b><b>--cleanup=</b><I>&lt;mode&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies how the auto-generated commit message (e.g., from <i>--amend</i>) should be cleaned up. Common modes include <i>strip</i> (strip comments and whitespace), <i>whitespace</i> (only strip leading/trailing whitespace), <i>verbatim</i>, and <i>scissors</i>.<br><br>


title: DESCRIPTION
content:
<i>dolt-commit</i> is a foundational command within the Dolt version control system for databases. It operates analogously to <i>git commit</i>, taking all changes that have been explicitly staged using <i>dolt add</i> (or automatically staged with the <i>-a</i>/<i>--all</i> option) and permanently recording them as a new snapshot in the database's history.<br><br>Each successful commit creates an immutable point-in-time representation of the database's schema and data. These commits are linked together, forming a directed acyclic graph (DAG) that constitutes the complete version history of the Dolt database, enabling powerful operations like branching, merging, diffing, and reverting data and schema.<br><br>A commit message is mandatory and should succinctly describe the changes introduced in the snapshot, aiding future understanding and navigation of the database's evolution.


title: CAVEATS
content:
Using the <i>--amend</i> option rewrites the commit history. While useful for local changes, it should be used with extreme caution on branches that have already been pushed to a remote Dolt database, as it can cause conflicts for collaborators.<br><br>Unless the <i>--all</i> or <i>--allow-empty</i> options are used, <i>dolt commit</i> requires that changes have been previously staged using <i>dolt add</i>.


title: COMMIT MESSAGE BEST PRACTICES
content:
A well-crafted commit message is crucial for understanding the history of your Dolt database. It should typically consist of a concise, single-line summary (under 50-72 characters) followed by a blank line and then a more detailed explanation of the changes. The summary should be in the imperative mood (e.g., "Add new 'users' table" rather than "Added new 'users' table"). Clear messages greatly enhance collaboration and future maintainability.


title: ATOMIC COMMITS
content:
It is generally considered good practice to make 'atomic' commits, meaning each commit should represent a single, logical change. This makes the history easier to understand, revert, or cherry-pick specific changes if needed. For example, separate schema changes from data changes, or changes to one table from changes to another, into distinct commits.


title: HISTORY
content:
<i>dolt-commit</i> is a core component of Dolt, a unique SQL database that blends traditional relational database features with Git-like version control capabilities. Dolt was created by DoltHub (formerly Liquidata) and first publicly released around 2019. The concept of <i>commit</i> is central to Dolt's design, directly inspired by Git's model of atomic snapshots. From its inception, <i>dolt commit</i> has been the primary mechanism for users to save and track changes to both schema and data, enabling the robust versioning, branching, and merging that defines the Dolt experience.


title: SYNOPSIS
content:
<b>dolt config</b> [<I>scope-options</I>] <I>subcommand</I> [<I>arguments</I>]<br><br>Examples of <I>scope-options</I>:<br>&nbsp;&nbsp;<b>--global</b><br>&nbsp;&nbsp;<b>--local</b><br>&nbsp;&nbsp;<b>--system</b><br>&nbsp;&nbsp;<b>--file=&lt;path&gt;</b><br><br>Examples of <I>subcommands</I>:<br>&nbsp;&nbsp;<b>--add</b> <I>&lt;key&gt;</I> <I>&lt;value&gt;</I><br>&nbsp;&nbsp;<b>--get</b> <I>&lt;key&gt;</I><br>&nbsp;&nbsp;<b>--set</b> <I>&lt;key&gt;</I> <I>&lt;value&gt;</I><br>&nbsp;&nbsp;<b>--list</b><br>&nbsp;&nbsp;<b>--edit</b><br>&nbsp;&nbsp;<b>--unset</b> <I>&lt;key&gt;</I>


title: PARAMETERS
content:
<b><b>--global</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the user's global configuration file, typically located at <I>~/.doltconfig</I>.<br><br><b><b>--local</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the current repository's local configuration file, located at <I>&lt;repo&gt;/.dolt/config</I>. This is the default scope if no scope option is provided.<br><br><b><b>--system</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the system-wide configuration file, typically found at <I>/etc/dolt/config</I>.<br><br><b><b>--file=&lt;path&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the configuration file specified by <I>&lt;path&gt;</I>, overriding default scope locations.<br><br><b><b>--add &lt;key&gt; &lt;value&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new line to the configuration file with the specified key and value. Useful for keys that can have multiple values.<br><br><b><b>--get &lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the value for the specified configuration <I>key</I>.<br><br><b><b>--get-all &lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves all values for a configuration <I>key</I> that may appear multiple times.<br><br><b><b>--set &lt;key&gt; &lt;value&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or updates the value for the specified configuration <I>key</I>. If the key exists, its value is updated; otherwise, it's added.<br><br><b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all configuration keys and their values across all active scopes (local, global, system), showing which file each value comes from.<br><br><b><b>--edit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the specified configuration file (or the default local config if no scope is specified) in a text editor for manual editing.<br><br><b><b>--unset &lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the specified configuration <I>key</I> and its value from the relevant configuration file.<br><br><b><b>--unset-all &lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all occurrences of the specified configuration <I>key</I> and its values.<br><br><b><b>--rename-section &lt;old-section&gt; &lt;new-section&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Renames a configuration section (e.g., 'user' to 'author').<br><br><b><b>--remove-section &lt;section&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes an entire configuration section and all its keys.<br><br><b><b>--get-bool &lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves a boolean configuration key, returning 'true' or 'false'.<br><br><b><b>--get-int &lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves an integer configuration key.<br><br><b><b>--set-int &lt;key&gt; &lt;value&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets an integer configuration key to the specified value.<br><br>


title: DESCRIPTION
content:
The <I>dolt config</I> command is used to read, write, and manage configuration options for Dolt repositories. Similar to <I>git config</I>, it allows users to customize Dolt's behavior at different levels: system-wide, globally for a user, or locally for a specific Dolt repository.<br><br>These configuration settings control various aspects of Dolt, such as user identity (name and email for commits), default text editors, remote URLs, and other operational preferences. The hierarchical nature of configuration means that local settings override global settings, which in turn override system-wide settings, providing flexibility in how Dolt behaves in different contexts. It's an essential tool for personalizing and standardizing Dolt environments.


title: CAVEATS
content:
When setting configuration values, Dolt applies them to the current scope (local by default, or specified by <b>--global</b>, <b>--system</b>, or <b>--file</b>). When getting values, Dolt searches in a specific order: local, then global, then system, returning the first value found. Be mindful of this precedence when troubleshooting configuration issues, as a value set in a more specific scope will override one in a broader scope. Ensuring a valid text editor is configured (e.g., via the <I>core.editor</I> key) is crucial for using the <b>--edit</b> command.


title: CONFIGURATION FILE LOCATIONS AND PRECEDENCE
content:
Dolt looks for configuration files in a specific order and applies settings based on precedence, with more specific scopes overriding broader ones:<br>1. <I>Local</I>: <I>&lt;repo&gt;/.dolt/config</I> - Specific to the current Dolt repository.<br>2. <I>Global</I>: <I>~/.doltconfig</I> - Applies to the current user across all Dolt repositories.<br>3. <I>System</I>: <I>/etc/dolt/config</I> - Applies to all users on the system.<br><br>When resolving a configuration key, Dolt will return the value found in the most specific scope first. For example, a setting in <I>.dolt/config</I> will override the same setting in <I>~/.doltconfig</I>.


title: HISTORY
content:
The Dolt project, developed by Liquidata, began in 2018 with the goal of bringing Git-like version control to SQL databases. The <I>dolt config</I> command was included from early versions, mirroring the functionality and hierarchical configuration model of Git's well-established <I>git config</I> command. This design choice aimed to provide a familiar and powerful way for users to manage their Dolt environment and customize database versioning behavior, consistent with best practices from distributed version control systems.


title: SEE ALSO
content:
<b>git config</b>(1): The primary inspiration for Dolt's configuration system, sharing much of its design and functionality., <b>dolt init</b>(1): Initializes a Dolt repository, which creates the local configuration file in <I>.dolt/config</I>., <b>dolt remote</b>(1): Manages sets of tracked repositories, often involving configuration settings for remote URLs (e.g., <I>remote.&lt;name&gt;.url</I>)., <b>dolt user</b>(1): A convenience command to set user identity configurations (<I>user.name</I> and <I>user.email</I>) globally or locally.


title: SYNOPSIS
content:
<b>dolt fetch</b> [<I>options</I>] [<I>remote</I> [<I>refspec</I>...]]<br><b>dolt fetch</b> <B>--all</B> [<I>remote</I>...]


title: PARAMETERS
content:
<b><I>remote</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the remote repository to fetch from. If omitted and <b>--all</b> is not specified, Dolt fetches from all configured remotes.<br><br><b><I>refspec</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies which remote references (branches, tags) to fetch and where to put them locally. It's typically in the format <i>[+]&lt;src&gt;:&lt;dst&gt;</i>. If not provided, Dolt uses default refspecs configured for the remote.<br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fetch from all configured remotes.<br><br><b><b>-p</b>, <b>--prune</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;After fetching, remove any remote-tracking branches that no longer exist on the remote. This cleans up stale references.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When using a refspec, allow updates to a local ref that is not a fast-forward. This can overwrite local remote-tracking branches, use with caution.<br><br><b><b>-n</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform all operations except actually sending the updates. Shows what would happen without modifying the repository.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be more verbose during the fetch operation, showing more details about the process.<br><br><b><b>--no-tags</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not fetch tags from the remote repository, even if the default refspecs would otherwise fetch them.<br><br>


title: DESCRIPTION
content:
<i>dolt fetch</i> is a command in the <I>Dolt</I> version-controlled SQL database that mirrors the functionality of <I>git fetch</I>. It is used to download branches and their associated commit history from one or more remote <I>Dolt</I> repositories to your local <I>Dolt</I> repository. <br><br>Unlike <I>dolt pull</I>, which fetches and then immediately merges changes into your current working branch, <I>dolt fetch</I> only downloads the data. It updates your local remote-tracking branches (e.g., <i>remotes/origin/main</i>) to reflect the state of the remote repository's branches. This allows you to inspect changes from the remote without altering your local working branch, providing a safe way to see what's new before integrating it. It's a crucial step for keeping your local database repository synchronized with remote collaborators and for preparing to merge remote changes.


title: CAVEATS
content:
<b>dolt fetch</b> only downloads data; it does not automatically merge changes into your current working branch. To integrate changes, you typically follow a fetch with a <b>dolt merge</b> or use <b>dolt pull</b> for a combined fetch-and-merge operation. Ensure you have remotes configured using <b>dolt remote add</b> before attempting to fetch. Fetching can download a significant amount of data, increasing local repository size.


title: DATABASE VERSION CONTROL
content:
The primary distinction of <b>dolt fetch</b> compared to <b>git fetch</b> is its application to a SQL database. It fetches schema and data changes, allowing users to track and manage evolutions of their database structure and content over time as commits and branches. This enables collaborative development on database schemas and data sets.


title: REMOTE-TRACKING BRANCHES
content:
When you fetch from a remote, <b>dolt fetch</b> updates 'remote-tracking branches' (e.g., <i>remotes/origin/main</i>). These branches are local copies of branches on the remote repository. They serve as bookmarks to show the exact state of the remote branches at the time of the last fetch. Your local working branches (e.g., <i>main</i>) are not affected by <b>dolt fetch</b> directly, giving you control over when and how you integrate changes.


title: HISTORY
content:
<b>Dolt</b> was created by DoltHub, Inc. with the goal of bringing Git-like version control semantics to SQL databases. The project started in 2018, building upon the Noms data format. As a core distributed version control operation, <b>dolt fetch</b> was fundamental from early stages, mimicking its Git counterpart to enable collaborative database development where users can synchronize their database state with remote repositories. It reflects Dolt's commitment to providing a familiar command-line experience for users accustomed to Git.


title: SEE ALSO
content:
dolt-pull(1), dolt-clone(1), dolt-remote(1), dolt-branch(1), dolt-merge(1), git-fetch(1) (conceptual parallel)


title: SYNOPSIS
content:
<b>dolt gc</b> [<b>--auto</b>] [<b>--prune</b>=<I>mode</I>] [<b>--expire</b>=<I>time</I>] [<b>--dry-run</b>]


title: PARAMETERS
content:
<b><b>--auto</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs garbage collection in an 'automatic' mode. This mode is typically less aggressive and designed for periodic, background execution. It might skip some pruning that a manual run would perform, making it suitable for automated maintenance tasks.<br><br><b><b>--prune</b>=<I>mode</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines how aggressively unreachable objects are pruned. <br>Possible modes include:<br><b>now</b>: Prunes all unreachable objects immediately.<br><b>expire</b>: (Default) Prunes objects that are older than the time specified by <b>--expire</b>.<br><b>never</b>: Does not prune any unreachable objects, effectively just cleaning up loose objects without removing old history.<br><br><b><b>--expire</b>=<I>time</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the minimum age for unreachable objects to be considered for pruning when <b>--prune=expire</b> is used. Objects older than this time will be removed. <br>Time can be specified in formats like '2.weeks', '3.months', '5.days', '1.hour'. The default is often 2 weeks.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulated run of the garbage collection without actually deleting any objects. It shows what would be removed, allowing users to verify the impact before committing to the operation. This is highly recommended for understanding the effects of different pruning strategies.<br><br>


title: DESCRIPTION
content:
The <b>dolt gc</b> command, short for 'garbage collection', is used to clean up unreferenced objects within a Dolt repository. <br><br>Dolt, being a version-controlled database, keeps a complete history of all data changes. Over time, as branches are merged, rebased, or deleted, and as new commits are made, some data objects (like old versions of tables or rows) may become 'unreachable' – meaning they are no longer part of any current branch, tag, or accessible via the reflog (after a certain expiry period). These unreachable objects can accumulate and consume significant disk space. <br><br><b>dolt gc</b> identifies these unreachable objects and removes them from the repository, thereby freeing up disk space and making the repository more efficient. It's analogous to <b>git gc</b> in Git. While generally safe, as it only removes truly unreferenced data, understanding its parameters is important to control its aggressiveness.


title: CAVEATS
content:
While <b>dolt gc</b> is designed to be safe and only remove truly unreachable data, users should be aware:<br>- If you rely on the reflog to recover very recent, unpushed work (e.g., deleted branches) and run <b>dolt gc --prune=now</b>, that data might be permanently lost if it falls outside the reflog's expiry period or explicit reachability.<br>- For very large repositories, running <b>dolt gc</b> can be a resource-intensive operation, consuming CPU and I/O. It's advisable to run it during periods of low activity if performance is critical.<br>- Ensure all important data is pushed to a remote if you intend to prune aggressively on local repositories that might not contain all remote branches or tags.


title: HOW IT WORKS
content:
<b>dolt gc</b> operates by identifying all data objects that are currently referenced by any branch, tag, active reflog entry, or commit. Any data object not reachable through these references is considered 'unreachable'. Depending on the <b>--prune</b> mode and <b>--expire</b> time, these unreachable objects are then safely removed from the repository, compacting its storage.


title: AUTOMATIC VS. MANUAL EXECUTION
content:
The <b>--auto</b> flag makes <b>dolt gc</b> suitable for automatic background maintenance, performing less aggressive pruning. Manual runs without <b>--auto</b> (or with specific <b>--prune</b> flags) are typically more thorough and are useful when significant disk space needs to be reclaimed after extensive history rewriting or branch deletion.


title: HISTORY
content:
Dolt is a relatively modern, Git-like version-controlled database. The <b>gc</b> (garbage collection) command is a fundamental feature inherited from version control systems like Git, crucial for maintaining repository efficiency and managing disk space. It has been an integral part of Dolt since its early development, reflecting the need to manage object storage and historical data effectively within a database context. Its design closely mirrors <b>git gc</b>, adapting the principles of object reachability and pruning to the Dolt data model.


title: PARAMETERS
content:
<b><i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The directory where the new <I>Dolt</I> repository will be initialized. If omitted, the repository is initialized in the current working directory.<br><br>


title: DESCRIPTION
content:
<i>dolt-init</i> initializes a new <I>Dolt</I> database repository in the current directory or a specified path. Analogous to <I>git init</I> for Git repositories, <I>dolt-init</I> sets up the necessary <I>Dolt</I> internal structures, including the <I>.dolt</I> directory. This hidden directory stores all database history, schema, and data. This command is the foundational step and must be executed before any other <I>Dolt</I> commands that operate on a repository (e.g., <I>dolt add</I>, <I>dolt commit</I>, <I>dolt status</I>).<br><br>When executed without a path, it initializes the repository in the current working directory. If a <I>path</I> is provided, <I>dolt-init</I> will create the directory if it doesn't exist and then initialize the repository within it. It establishes an empty <I>main</I> branch, preparing the directory for database version control. The command ensures the chosen location is ready to be managed as a <I>Dolt</I> database, allowing users to begin tracking schema and data changes.


title: CAVEATS
content:
Initializing a <I>Dolt</I> repository inside an already existing <I>.dolt</I> directory is not permitted and will result in an error or a message indicating that the repository is already initialized. The <I>.dolt</I> directory contains critical internal data; direct manual manipulation of its contents is strongly discouraged as it can corrupt the repository. Always use <I>Dolt</I> commands to interact with the repository's state.


title: IDEMPOTENCY
content:
Running <I>dolt-init</I> in a directory that is already a <I>Dolt</I> repository typically has no effect or provides an informational message stating that it is already initialized. It generally does not re-initialize or corrupt an existing repository.


title: .DOLT DIRECTORY
content:
Upon initialization, a hidden directory named <I>.dolt</I> is created at the root of the repository. This directory is crucial as it stores all the version history, including commits, branches, and the underlying data. It should not be manually modified or deleted.


title: HISTORY
content:
<I>Dolt</I> was developed by DoltHub (formerly Liquidata) and open-sourced in 2019, introducing the concept of a Git-like version-controlled database. The <I>dolt-init</I> command has been a core component since its inception, mimicking the behavior and purpose of <I>git init</I> to provide the essential first step for users to begin versioning their SQL databases. Its design reflects <I>Dolt</I>'s philosophy of bringing familiar Git semantics to database management.


title: PARAMETERS
content:
<b><I>commit-ish</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The branch name, tag, or commit hash to merge into the current HEAD.<br><br><b>-m, --no-ff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a merge commit even if the merge could be resolved as a fast-forward. This ensures a merge commit is always created.<br><br><b>-ff-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only perform a fast-forward merge. Fail if the merge cannot be resolved as a fast-forward.<br><br><b>--abort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Abort the current merge in progress, restoring the state before the merge attempt.<br><br><b>--continue</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Continue the merge after resolving conflicts. This should be used after manually fixing conflicts.<br><br><b>--squash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform the merge and stage the changes, but do not create a merge commit. The user can then commit these changes as a single, new commit.<br><br><b>--allow-empty-commit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a merge commit even if no changes result from the merge. This is typically used with --no-ff.<br><br><b>--allow-data-conflict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows data conflicts to persist in the database after the merge. <I>Use with extreme caution, as it can lead to inconsistent states.</I><br><br><b>--allow-schema-conflict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows schema conflicts to persist in the database after the merge. <I>Use with extreme caution, as it can lead to inconsistent states.</I><br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress non-error messages during the merge process.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more detailed output during the merge process.<br><br><b>-X<I>strategy</I>, --strategy=<I>strategy</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the merge strategy. Currently, 'recursive' is the primary and default strategy in Dolt.<br><br>


title: DESCRIPTION
content:
<b>dolt-merge</b> is a fundamental command in Dolt, a version-controlled SQL database. It functions analogously to <i>git merge</i>, allowing users to integrate changes from one Dolt branch or commit into another. When executed, <b>dolt-merge</b> attempts to combine the history of two diverging lines of development. It handles both schema (table definitions) and data (row content) conflicts. If a fast-forward merge is possible, where the current branch's head is an ancestor of the merged branch's head, Dolt will perform a fast-forward by default, simply moving the current branch pointer. Otherwise, it performs a three-way merge, creating a new merge commit that integrates the changes from both branches, resolving conflicts where necessary. Users can explicitly control the merge behavior using various options, such as forcing a merge commit or allowing only fast-forward merges. Conflict resolution is a key aspect, requiring manual intervention for unresolvable differences in schema or data.


title: CAVEATS
content:
When <b>dolt-merge</b> encounters conflicts, the merge process will pause, and the database will be left in a conflicted state. Users must manually resolve these conflicts (using tools like <b>dolt diff</b> and <b>dolt resolve</b>) before continuing the merge. Using the <b>--allow-data-conflict</b> or <b>--allow-schema-conflict</b> options can leave the database in an inconsistent or problematic state, making future operations difficult and should generally be avoided unless absolutely necessary for specific recovery scenarios.


title: CONFLICT RESOLUTION WORKFLOW
content:
When <b>dolt-merge</b> encounters conflicts (differences that cannot be automatically resolved), it will leave markers in the affected tables or schemas, and the merge process will pause. The command will provide guidance on how to resolve these conflicts. Users must then manually edit the conflicted tables/schema using standard SQL tools or Dolt's conflict resolution commands (e.g., <b>dolt resolve</b>). After all conflicts are resolved and changes are staged, the merge can be completed by running <b>dolt merge --continue</b>.


title: MERGE STRATEGIES
content:
While Git offers multiple merge strategies, Dolt primarily uses a <b>recursive</b> strategy for its merges by default. This strategy is robust and capable of handling complex histories involving multiple common ancestors, similar to Git's default merge behavior for complex merges. Other strategies found in Git (like `ours` or `theirs` for path-based resolution) are managed differently in Dolt through explicit table operations or conflict resolution.


title: HISTORY
content:
Dolt was created by DoltHub, Inc., as a version-controlled SQL database. Its design is heavily inspired by Git, aiming to bring Git-like functionalities (branching, merging, diffing) to databases. <b>dolt-merge</b> is a core command reflecting this design philosophy, enabling collaborative development and schema/data evolution in a highly structured manner, similar to how source code is managed. The first stable release of Dolt was in 2020, and active development continues.


title: SEE ALSO
content:
dolt diff(1), dolt status(1), dolt commit(1), dolt resolve(1), dolt reset(1), dolt rebase(1), git merge(1)


title: PARAMETERS
content:
<b><b>-q</b>, <b>--query</b> <i><query_string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the specified SQL <i>query_string</i> and exits.<br><br><b><b>-f</b>, <b>--filename</b> <i><file_path></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes SQL commands from the given <i>file_path</i>.<br><br><b><b>-H</b>, <b>--host</b> <i><hostname></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the hostname of the Dolt SQL server to connect to. Default is 'localhost'.<br><br><b><b>-P</b>, <b>--port</b> <i><port_number></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number of the Dolt SQL server to connect to. Default is '3306'.<br><br><b><b>-u</b>, <b>--user</b> <i><username></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username for connecting to a Dolt SQL server.<br><br><b><b>-p</b>, <b>--password</b> <i><password></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the password for connecting to a Dolt SQL server. If not provided for a user requiring one, it will be prompted.<br><br><b><b>--read-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the Dolt database in read-only mode, preventing any modifications.<br><br><b><b>--branch</b> <i><branch_name></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the branch to query or operate on. Useful when working with different data versions.<br><br><b><b>--format</b> <i><output_format></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output format for query results (e.g., <i>csv</i>, <i>json</i>, <i>tabular</i>, <i>html</i>, <i>xml</i>, <i>json-array</i>, <i>json-table</i>, <i>vertical</i>). Default is 'tabular' for interactive mode.<br><br>


title: DESCRIPTION
content:
The <b>dolt sql</b> command provides a command-line interface (CLI) for interacting with the SQL engine of a Dolt database. Dolt is a unique database that combines the features of a relational database with the version control capabilities of Git. Using <b>dolt sql</b>, users can execute standard SQL queries directly against their Dolt repositories.<br><br>It supports two primary modes of operation: <i>interactive shell</i> and <i>single query execution</i>. In interactive mode, it provides a MySQL-compatible SQL shell, allowing users to type and execute queries sequentially. For single query execution, the <b>--query</b> (<b>-q</b>) flag is used to pass a SQL statement directly, making it suitable for scripting. Additionally, queries can be read from a file using the <b>--filename</b> (<b>-f</b>) flag.<br><br>Beyond local repository interaction, <b>dolt sql</b> can also act as a client to connect to a running <b>dolt sql-server</b> instance, enabling remote access and multi-user environments. Its aim is to provide a familiar SQL experience while leveraging Dolt's powerful data versioning, branching, merging, and diffing capabilities.


title: CAVEATS
content:
While <b>dolt sql</b> strives for MySQL compatibility, it is not 100% identical. Users might encounter minor differences in supported functions, data types, or specific SQL syntax. Performance characteristics may also differ from traditional RDBMS due to Dolt's underlying Git-like versioning architecture.


title: INTERACTIVE MODE
content:
When run without the <b>--query</b> or <b>--filename</b> flags, <b>dolt sql</b> enters an interactive SQL shell. This shell provides a familiar experience similar to the MySQL client, allowing users to type and execute multiple SQL statements sequentially, manage sessions, and see query results directly.


title: LOCAL VS. SERVER CONNECTION
content:
By default, <b>dolt sql</b> operates on the Dolt repository in the current directory (or one specified by <b>--data-dir</b>). However, it can also function as a client to connect to a remotely running <b>dolt sql-server</b> instance, using the <b>--host</b>, <b>--port</b>, <b>--user</b>, and <b>--password</b> flags. This distinction allows for both standalone local development and multi-user server-based deployments.


title: HISTORY
content:
Dolt was developed by DoltHub (originally Liquidata) with the vision of bringing Git-like version control to data. The <b>dolt sql</b> command has been a foundational component of the Dolt ecosystem since its inception, enabling users to interact with their versioned data using familiar SQL syntax. Its evolution has focused on expanding SQL compatibility, enhancing performance, and integrating seamlessly with Dolt's unique branching, merging, and diffing capabilities.


title: PARAMETERS
content:
<b>None</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <i>dolt status</i> command does not accept any command-specific parameters beyond common global Dolt flags (e.g., --help), as its function is simply to display the current state.<br><br>


title: DESCRIPTION
content:
The <i>dolt status</i> command displays the state of the Dolt working directory and staging area. It provides a concise summary, showing which data and schema changes are ready to be committed, which have been modified but not yet staged, and which tables are entirely new and untracked. This command is a fundamental tool for understanding the current state of your Dolt database, helping users track their modifications before committing them to the version history. It helps bridge the gap between your local database modifications and the versioned snapshots managed by Dolt. It is inspired by and functions similarly to <i>git status</i>.


title: CAVEATS
content:
While <i>dolt status</i> provides a comprehensive overview of the working directory, it only reflects changes relative to the current HEAD of the branch. It does not show changes that exist only in other branches until you switch to them. It also won't reflect changes that are not saved to the working directory (e.g., pending database transactions that haven't been materialized to Dolt's working set).


title: OUTPUT SECTIONS
content:
<i>dolt status</i> typically organizes its output into several distinct sections:<br><b>Untracked tables:</b> Lists tables that exist in your working directory but are not yet tracked by Dolt's version control. These can be added using <i>dolt add &lt;table-name&gt;</i>.<br><b>Tables/schema to be committed:</b> Shows changes (data or schema) that have been staged using <i>dolt add</i> and are ready to be included in the next commit.<br><b>Changes not staged for commit:</b> Displays modifications to existing, tracked tables or schema that have not yet been added to the staging area. These changes can be staged using <i>dolt add &lt;table-name&gt;</i>.<br><b>Unmerged paths:</b> (Less common for simple usage) If a merge conflict occurs, this section will list tables with conflicts that need to be resolved before committing.


title: HISTORY
content:
The <i>dolt status</i> command is an integral part of the Dolt database system, which was first publicly released by DoltHub in 2018. As Dolt aims to be a Git-like version control system for data, the design and functionality of <i>dolt status</i> were heavily influenced by Git's widely adopted <i>git status</i> command. Its inclusion from the early stages of Dolt's development underscores the importance of transparently tracking and managing data changes within a versioned database environment. Its evolution has mirrored the overall development of Dolt, improving its output clarity and performance.


title: PARAMETERS
content:
<b><B>--help</B>, <B>-h</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <I>dolt version</I> command, including available flags and usage examples, helping users understand its capabilities.<br><br><b><B>--json</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the Dolt client version and build information in a structured JSON format. This is particularly useful for scripting, automation, and integration with other tools that require programmatic access to version details.<br><br>


title: DESCRIPTION
content:
The <I>dolt version</I> command outputs the installed client version of Dolt, a SQL database that supports Git-like versioning. This command is essential for users and developers to quickly identify the specific build of the Dolt client they are currently using. The output typically includes the Dolt client's build number, the git commit hash it was built from, the build date, and sometimes the platform information. This detailed version information is crucial for verifying compatibility with Dolt SQL servers, troubleshooting issues, reporting bugs accurately, and ensuring that specific features or bug fixes are present. It serves as a foundational piece of information when dealing with any Dolt-related task or support inquiry. The optional <B>--json</B> flag provides a machine-readable format of this information, facilitating automated checks and integrations.


title: CAVEATS
content:
The <B>dolt version</B> command specifically reports the <I>client</I> version of Dolt. It does not provide information about a connected Dolt SQL server's version, if Dolt is being used in a client-server architecture. For server version details, users should typically query the database directly (e.g., by executing <I>SELECT VERSION()</I> within a Dolt SQL session or client).


title: PURPOSE OF VERSIONING
content:
Beyond simple identification, version information is vital for ensuring reproducibility of environments, confirming the availability of specific Dolt features or bug fixes, and for coordinating development across teams by standardizing on particular Dolt client versions.


title: JSON OUTPUT UTILITY
content:
The <B>--json</B> flag makes <I>dolt version</I> machine-readable, enabling scripting and automation where Dolt client version checks are necessary. This is especially useful in CI/CD pipelines, deployment scripts, or automated diagnostic tools, allowing for dynamic system configurations or health checks based on the installed Dolt client version.


title: HISTORY
content:
Dolt is developed by DoltHub, Inc. and was first publicly released in 2019, introducing a novel approach to data management by integrating Git-like version control capabilities directly into a SQL database. Its core innovation allows users to branch, merge, diff, and clone data, treating entire databases as versioned repositories. The <I>version</I> command has been a fundamental and indispensable part of the Dolt Command Line Interface (CLI) since its initial release, providing immediate and accessible feedback on the installed client's specific build details. Its continued presence and utility underscore the project's commitment to transparency and ease of debugging, crucial aspects for a tool bridging traditional databases with modern version control paradigms.


title: PARAMETERS
content:
<b><i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> The desired NIS/YP domain name to set. Requires superuser privileges. If omitted, the current NIS domain name is displayed.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<i>domainname</i> is a command-line utility used to query or set the Network Information Service (NIS), formerly known as Yellow Pages (YP), domain name of the current system.<br><br>When invoked without any arguments, it displays the currently configured NIS domain name. If an argument (the desired domain name) is provided, <i>domainname</i> attempts to set the system's NIS domain name. It's crucial to understand that this command manages the NIS domain name, which is distinct from the DNS domain name used for internet name resolution. Setting the NIS domain name typically requires superuser privileges and is often temporary for the current session, meaning it won't persist across reboots unless configured via system-specific startup scripts or network configuration files. NIS is an older client/server directory service primarily used for distributing configuration data like user accounts and hostnames across a network.


title: CAVEATS
content:
Setting the NIS domain name using <i>domainname &lt;name&gt;</i> usually requires <b>root privileges</b>.<br>The change made by <i>domainname &lt;name&gt;</i> is typically <b>not persistent</b> across system reboots. For permanent changes, refer to your operating system's network configuration documentation (e.g., /etc/sysconfig/network on Red Hat-based systems, /etc/defaultdomain or similar on others).<br>This command manages the <b>NIS/YP domain name</b>, which is conceptually different from the <b>DNS domain name</b> used for internet name resolution. Do not confuse the two.


title: NIS VS. DNS DOMAIN
content:
It is a common misconception that <b>domainname</b> refers to the DNS domain name. In reality, <b>domainname</b> manages the NIS (Network Information Service) or YP (Yellow Pages) domain name. The DNS domain name, used for resolving hostnames to IP addresses on the internet and local networks, is typically displayed by the <b>dnsdomainname(1)</b> command or derived from your DNS resolver configuration (e.g., <b>/etc/resolv.conf</b>).


title: MAKING CHANGES PERSISTENT
content:
While <b>domainname &lt;name&gt;</b> sets the NIS domain name for the current session, this change is not permanent. To ensure the NIS domain name is set automatically upon system boot, you must configure it in system-specific network configuration files. Common locations or methods include setting <b>NISDOMAIN</b> in <b>/etc/sysconfig/network</b> (Red Hat/CentOS), defining it in <b>/etc/defaultdomain</b>, or through network manager configurations, depending on your Linux distribution.


title: HISTORY
content:
The <i>domainname</i> command has its origins in Sun Microsystems' Network Information Service (NIS), originally called Yellow Pages (YP). Due to trademark issues, "Yellow Pages" was renamed to NIS. The command has been a staple in Unix-like operating systems that supported NIS for distributing system configuration data. It's typically part of the <i>net-tools</i> or <i>nis-tools</i> packages. While once prevalent, the use of NIS has declined significantly in favor of more modern and secure distributed directory services like LDAP and Kerberos, and DNS for primary name resolution.


title: SYNOPSIS
content:
Since <I>done</I> is a keyword and not a standalone command, its "synopsis" describes its usage within shell loop structures:<br><br><b><I>for</I></b> <I>VARIABLE</I> <b><I>in</I></b> <I>LIST</I><I>;</I> <b><I>do</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>commands</I><br><b><I>done</I></b><br><br><b><I>while</I></b> <I>CONDITION</I><I>;</I> <b><I>do</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>commands</I><br><b><I>done</I></b><br><br><b><I>until</I></b> <I>CONDITION</I><I>;</I> <b><I>do</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>commands</I><br><b><I>done</I></b><br><br><b><I>select</I></b> <I>VARIABLE</I> <b><I>in</I></b> <I>LIST</I><I>;</I> <b><I>do</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>commands</I><br><b><I>done</I></b>


title: PARAMETERS
content:
<b>N/A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The '<I>done</I>' keyword does not accept parameters or options; it solely serves as a structural delimiter in shell loops.<br><br>


title: DESCRIPTION
content:
<I>done</I> is <I>not</I> a standalone executable command on Linux systems. Instead, it is a fundamental keyword used in various shell scripting constructs, primarily to mark the end of a <I>do...done</I> block for loops. It signifies the conclusion of the command list that is executed repeatedly within <I>for</I>, <I>while</I>, <I>until</I>, and <I>select</I> loops. It plays a crucial role in defining the scope of operations that are part of an iterative process in shell scripts. Without the <I>done</I> keyword, shell parsers would not be able to correctly identify the boundaries of loop bodies, leading to syntax errors. Its purpose is purely structural, defining control flow rather than performing an action itself.


title: CAVEATS
content:
<I>done</I> is a keyword in shell scripting, not an executable command. Attempting to run <I>done</I> directly in a terminal will result in a "command not found" error. Its functionality is strictly tied to shell loop constructs (<I>for</I>, <I>while</I>, <I>until</I>, <I>select</I>), where it marks the end of the block of commands to be executed. It should not be confused with the concept of job completion or a "task done" utility, unless such a utility has been specifically aliased or scripted by a user.


title: USAGE EXAMPLE
content:
Here is a simple example demonstrating the use of the <I>done</I> keyword within a <I>for</I> loop:<br><br><b><I>#!/bin/bash</I></b><br><b><I>for</I></b> <I>i</I> <b><I>in</I></b> <I>1 2 3 4 5</I><I>;</I> <b><I>do</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><I>echo</I></b> <I>"Current number: $i"</I><br><b><I>done</I></b><br><b><I>echo</I></b> <I>"Loop finished."</I><br><br>This script will iterate through the numbers 1 to 5, printing the current number in each iteration, and then print "Loop finished." after the loop completes.


title: HISTORY
content:
The <I>done</I> keyword's history is inextricably linked to the evolution of Unix shells. It originated with the Bourne Shell (<I>sh</I>), introduced in 1977, as a fundamental component of its control flow syntax for loops. Its purpose, along with <I>do</I>, was to clearly delineate the block of commands to be repeatedly executed. This syntax was then inherited and maintained by subsequent shell implementations, including the Korn Shell (<I>ksh</I>), C Shell (<I>csh</I>), and notably the GNU Bourne-Again Shell (<I>bash</I>), which is the default shell on most Linux distributions today. Its consistent presence across various shells highlights its fundamental and stable role in shell scripting for defining iterative operations.


title: SEE ALSO
content:
<I>do</I>, <I>for</I>, <I>while</I>, <I>until</I>, <I>select</I>, <I>bash</I><I>(1)</I>, <I>sh</I><I>(1)</I>


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <b>doppler</b> command or a specific subcommand.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the current version of the Doppler CLI.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs command results in JSON format, suitable for programmatic parsing.<br><br><b>--project &lt;name|id&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Doppler project to operate on, overriding the default or configured project.<br><br><b>--config &lt;name|id&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Doppler config (environment) to operate on, overriding the default or configured config.<br><br><b>--scope &lt;scope&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the scope for certain commands, e.g., 'project' or 'config'.<br><br><b>--token &lt;token&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a service token for authentication, typically used in non-interactive environments.<br><br><b>--cwd &lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the current working directory for the command execution.<br><br><b>--no-check-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables automatic checks for new CLI updates.<br><br>


title: DESCRIPTION
content:
The <b>doppler</b> command is the official command-line interface (CLI) for the Doppler platform, a centralized system for managing secrets, environment variables, and configurations. It allows developers and operations teams to securely synchronize, inject, and access sensitive data across various environments, from local development to production. The CLI provides functionality to authenticate with the Doppler service, download and manage secrets, and execute applications with secrets injected directly into their environment. It integrates seamlessly into CI/CD pipelines, offering versioning, access control, and auditing capabilities for all secrets.


title: CAVEATS
content:
The <b>doppler</b> command requires an active Doppler account and network connectivity to the Doppler platform for most of its functionality.<br>Authentication via <b>doppler login</b> or a valid service token is necessary to access and manage secrets.<br>It is not a standalone utility for local secret storage; it relies on the cloud-based Doppler service.


title: SUBCOMMANDS
content:
The <b>doppler</b> command's primary functionality is exposed through a rich set of subcommands, each designed for specific tasks. Users typically interact with these subcommands rather than the top-level command directly. Examples include:<br><b>doppler login</b>: Authenticates the CLI with your Doppler account.<br><b>doppler secrets download</b>: Downloads secrets from a specified config.<br><b>doppler run</b>: Executes a command with secrets injected into its environment.<br><b>doppler configure</b>: Manages local project and config settings.<br><b>doppler projects</b>: Manages Doppler projects.<br><b>doppler configs</b>: Manages Doppler configurations (environments).


title: AUTHENTICATION
content:
For interactive use, authentication is typically handled via <b>doppler login</b>, which opens a browser for OAuth-based login. For CI/CD environments or automated scripts, service tokens or configuration files are used to authenticate the CLI.


title: HISTORY
content:
Doppler emerged as a modern solution to address the growing complexity of secrets management in cloud-native and microservices architectures. Its development has focused on providing a secure, auditable, and developer-friendly way to handle sensitive configurations, moving beyond traditional environment variables and insecure file storage. The CLI has evolved with features like dynamic secret injection and broad integration capabilities, reflecting the needs of contemporary DevOps practices.


title: SYNOPSIS
content:
<I>doppler</I> projects <I>&lt;command&gt;</I> [options]<br><br>Examples:<br><I>doppler</I> projects list<br><I>doppler</I> projects create --name my-new-project --description "A project for my application"<br><I>doppler</I> projects delete --project old-project --confirm


title: PARAMETERS
content:
<b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the command result in JSON format. This option is available across many <I>doppler</I> subcommands for programmatic parsing.<br><br><b>--name <I>&lt;name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the project. Required when creating a new project (<I>doppler projects create</I>) or providing a new name when updating (<I>doppler projects update</I>).<br><br><b>--description <I>&lt;description&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a textual description for the project. Optional when creating a new project (<I>doppler projects create</I>) or updating an existing one (<I>doppler projects update</I>).<br><br><b>--project <I>&lt;project_name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Identifies the target project for operations such as deletion (<I>doppler projects delete</I>) or updating (<I>doppler projects update</I>). Use the exact name of the project.<br><br><b>--confirm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypasses the interactive confirmation prompt, typically used for destructive actions like deleting a project (<I>doppler projects delete</I>), making it suitable for scripting.<br><br>


title: DESCRIPTION
content:
The <I>doppler projects</I> command group, part of the Doppler CLI, enables comprehensive management of Doppler projects directly from the terminal. Projects serve as the primary organizational units within Doppler for grouping secrets and configurations across different environments (e.g., development, staging, production). This command group provides functionalities to <I>list</I> existing projects, <I>create</I> new ones, <I>delete</I> projects, and <I>update</I> their details. It is an indispensable tool for developers and operations teams seeking to integrate secrets management into their automated workflows, scripting, and continuous delivery pipelines, ensuring secure and consistent application environments.


title: CAVEATS
content:
<b>Key Considerations:</b><br><I>doppler projects</I> requires the Doppler CLI to be installed and properly authenticated against your Doppler workspace.<br>User permissions within Doppler must be configured to allow project management operations (e.g., creating, deleting, or updating projects).<br>Deleting a project is an irreversible action that permanently removes all associated environments, configurations, and secrets. Exercise caution when using the <I>delete</I> subcommand.<br>The CLI may prompt for interactive input unless specific options like <I>--confirm</I> are used for scripting.


title: CORE FUNCTIONALITY
content:
The primary subcommands within <I>doppler projects</I> are:<br><I>list</I>: Displays all projects accessible to the current user.<br><I>create</I>: Establishes a new project with a specified name and optional description.<br><I>delete</I>: Permanently removes an existing project and all its associated data.<br><I>update</I>: Modifies the name or description of an existing project.


title: ORGANIZATIONAL HIERARCHY
content:
In Doppler's architecture, projects are the highest level of organization. Each project can contain multiple environments (e.g., 'dev', 'staging', 'prod'), and each environment can hold various configurations, which in turn store your actual secrets.


title: HISTORY
content:
The <I>doppler projects</I> subcommand group is an integral part of the Doppler Command Line Interface (CLI), which was developed to extend the functionality of the Doppler secrets management platform beyond its web-based user interface. Its introduction provided developers and operations teams with programmatic control over their projects, enabling seamless integration into automated workflows, CI/CD pipelines, and infrastructure as code practices. This CLI functionality has continuously evolved alongside the Doppler platform, enhancing its capabilities for scalable and secure secret management.


title: PARAMETERS
content:
<b>--project <name>, -p <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Doppler project from which to retrieve secrets.<br><br><b>--config <name>, -c <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Doppler configuration (e.g., 'dev', 'stg', 'prd') within the project.<br><br><b>--scope <scope></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters secrets to a specific scope within the chosen configuration.<br><br><b>--token <token></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticates with a Doppler Service Token instead of the logged-in user session. Commonly used in CI/CD environments.<br><br><b>--log-level <level></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging level for Doppler CLI output (e.g., 'info', 'warn', 'error').<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose logging for more detailed output.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug logging, providing the most detailed output for troubleshooting.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>doppler-run</i> command.<br><br>


title: DESCRIPTION
content:
<i>doppler-run</i> is a command-line utility provided by the Doppler CLI for secure secrets management. It executes a specified command, script, or program, dynamically injecting secrets from the Doppler platform directly into its environment variables. This mechanism prevents sensitive information, such as API keys and database credentials, from being hardcoded or exposed in plain text. When invoked, <i>doppler-run</i> retrieves secrets for the designated project and configuration, sets them as environment variables, and then spawns the target process. This approach significantly enhances security and streamlines secret management across development, staging, and production environments, eliminating the need for manual environment variable setup or complex .env files. It is widely used for running development servers, executing CI/CD pipelines, and other applications requiring secure access to sensitive data.


title: CAVEATS
content:
Requires the Doppler CLI to be installed and configured/authenticated.<br>Network connectivity to the Doppler service is essential for fetching secrets.<br>Secrets are exposed as environment variables, which might not be suitable for all applications or security models.<br>The executed command must be designed to consume configuration via environment variables.<br>Sensitive information temporarily resides in the environment of the child process.


title: AUTHENTICATION
content:
<i>doppler-run</i> primarily uses the authentication context established by a prior <i>doppler login</i> command. Alternatively, a Doppler Service Token can be provided directly via the <i>--token</i> parameter, which is common in automated environments like CI/CD.


title: ENVIRONMENT VARIABLE PRECEDENCE
content:
When <i>doppler-run</i> injects secrets, they typically take precedence over any existing environment variables with the same name. This ensures that the application receives the intended, securely managed secrets from Doppler.


title: LOCAL DEVELOPMENT
content:
While <i>doppler-run</i> fetches secrets from the remote Doppler service, the Doppler CLI can also work with local <i>.doppler</i> files for development. For inspecting what secrets would be injected, the <i>doppler secrets</i> command can be used.


title: HISTORY
content:
The <i>doppler-run</i> command is a core component of the Doppler secrets management platform. It emerged as a solution to address the challenges of securely providing sensitive data to applications, moving beyond static configuration files or insecure environment variables. Its development is intertwined with the increasing adoption of cloud-native architectures and the need for centralized, auditable, and version-controlled secrets. Since its inception, it has become a fundamental tool for integrating Doppler into various workflows, including local development, continuous integration/continuous deployment (CI/CD) pipelines, and serverless function deployments, ensuring secure and seamless secret injection.


title: SYNOPSIS
content:
<b>doppler secrets</b> <i>&lt;command&gt;</i> [<i>options</i>]<br><b>doppler secrets</b> <i>&lt;subcommand&gt;</i> [<i>flags</i>]


title: PARAMETERS
content:
<b><b>ls</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all secrets for the current project and configuration. Can be filtered or output in JSON format.<br><br><b><b>get</b> <i>&lt;secret_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the value of a specific secret. Requires the secret's name.<br><br><b><b>edit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens an interactive editor (e.g., `vi`, `nano`) to modify secrets for the current project and configuration.<br><br><b><b>download</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Downloads secrets to a local file, typically in `.env` or JSON format, allowing for easy integration with local applications.<br><br><b><b>upload</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uploads secrets from a local file (e.g., `.env`) to a Doppler project and configuration.<br><br><b><b>update</b> <i>&lt;secret_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the value of a specific secret directly from the command line, non-interactively.<br><br><b><b>rename</b> <i>&lt;old_name&gt;</i> <i>&lt;new_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Renames an existing secret.<br><br><b><b>delete</b> <i>&lt;secret_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a specific secret from the current project and configuration.<br><br><b><b>describe</b> <i>&lt;secret_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides details about a specific secret, including its value and related information.<br><br><b><i>--project &lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A global flag to specify the Doppler project to operate on. Overrides any context set by `doppler configure` or environment variables.<br><br><b><i>--config &lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A global flag to specify the Doppler configuration (environment) within the project. Overrides any context set by `doppler configure` or environment variables.<br><br><b><i>--json</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A global flag to output results in JSON format, useful for scripting and programmatic consumption.<br><br>


title: DESCRIPTION
content:
The <b>doppler-secrets</b> Linux command, typically invoked as <b>doppler secrets</b>, is part of the <i>Doppler CLI</i>, a powerful interface for interacting with the <i>Doppler Universal Secrets Platform</i>.<br><br>Doppler provides a centralized system for managing sensitive information like API keys, database credentials, and environment variables across all your application environments (development, staging, production). It helps development teams eliminate hardcoded secrets, reduce security risks, and ensure consistent secret management practices.<br><br>The <b>doppler secrets</b> subcommand specifically focuses on the management of individual secrets within your Doppler projects and configurations. It allows users to list, retrieve, modify, upload, and download secrets securely from the command line, making it an essential tool for integrating secrets into CI/CD pipelines, local development environments, and server deployments.


title: CAVEATS
content:
The <b>doppler secrets</b> command requires authentication with your Doppler account. This is typically done via <b>doppler login</b> or by setting the <b>DOPPLER_TOKEN</b> environment variable.<br><br>Proper project and configuration (environment) selection is critical to ensure you are managing secrets in the correct scope. Incorrect usage could lead to unintended exposure or modification of sensitive data.<br><br>The command relies on network connectivity to the Doppler API. Without it, secret operations will fail.


title: AUTHENTICATION
content:
Before using <b>doppler secrets</b>, you must authenticate the CLI with your Doppler account. This is typically done by running <b>doppler login</b> and following the prompts, or by setting the <b>DOPPLER_TOKEN</b> environment variable with a valid Doppler API token.


title: CONTEXT AND SCOPES
content:
The <b>doppler</b> CLI operates within a defined <i>project</i> and <i>configuration</i> (environment) context. This context can be set globally using <b>doppler configure</b>, or overridden per-command using the <i>--project</i> and <i>--config</i> flags. Understanding your current context is crucial for managing secrets effectively.


title: HISTORY
content:
Doppler was founded with the goal of providing a secure and scalable platform for managing application secrets. The <i>Doppler CLI</i>, including the <b>doppler secrets</b> subcommand, has been a core component of the Doppler ecosystem since its early days (around 2019-2020). Its development has focused on providing a seamless developer experience, integrating with popular tools and services, and adhering to best practices in secrets management. The command has evolved to support a wide range of secret operations, reflecting the growing complexity of modern application deployments.


title: SYNOPSIS
content:
<b>dos2unix</b> [<i>OPTIONS</i>] [<i>FILE</i> ...]<br>If no <i>FILE</i> is specified, <b>dos2unix</b> reads from standard input and writes to standard output.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and options.<br><br><b>-k, --keepdate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps the original modification date of the converted file.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all warning messages and output to standard error.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of the dos2unix utility.<br><br><b>-c, --convmode <I>MODE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the conversion mode. Common modes include <B>auto</B> (default, detects based on content), <B>dos</B> (CRLF to LF), <B>mac</B> (CR to LF), and <B>unix</B> (LF to LF, does nothing).<br><br><b>-o, --newfile <I>OUTPUT_FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the converted output to a specified new file instead of converting in-place. Requires a single input file.<br><br><b>-s, --suffix <I>SUFFIX</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a backup of the original file by appending <I>SUFFIX</I> to its name before conversion. For example, <B>.bak</B> or <B>.orig</B>.<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the end of options, useful when file names might begin with a hyphen (-).<br><br>


title: DESCRIPTION
content:
The <B>dos2unix</B> command is a utility designed to convert plain text files from <I>DOS</I> or <I>Macintosh</I> line ending conventions to the standard <I>Unix</I> line ending format.<br><br>Historically, different operating systems have used distinct character sequences to denote the end of a line in text files. <I>DOS</I>/<I>Windows</I> systems use a carriage return followed by a line feed (<B>CRLF</B> - <I>\r\n</I>), while <I>Macintosh</I> systems (pre-OSX) used only a carriage return (<B>CR</B> - <I>\r</I>). <I>Unix</I>-like systems, including <I>Linux</I>, exclusively use a line feed (<B>LF</B> - <I>\n</I>).<br><br>When text files created on <I>DOS</I> or <I>Macintosh</I> are transferred to a <I>Unix</I> environment, the differing line endings can cause issues, such as extra visible characters (<I>^M</I> for <B>CR</B>) or script execution problems. <B>dos2unix</B> resolves this by reading the input file and replacing <B>CRLF</B> or <B>CR</B> sequences with a single <B>LF</B>, making the file compatible with <I>Unix</I> text processing tools and scripts. It can convert files in-place or write to a new output file.


title: CAVEATS
content:
<b>dos2unix</b> is primarily designed for <B>text files</B>. Applying it to <B>binary files</B> (e.g., images, executables, compressed archives) can corrupt them, making them unusable. Always ensure the input file is a plain text file before conversion.<br><br>While it can handle <I>UTF-8</I> with or without a <I>Byte Order Mark</I> (<B>BOM</B>), <B>dos2unix</B> is <I>not</I> a general-purpose character encoding converter. Its main function is line ending normalization. For full encoding conversions, other tools like <B>iconv</B> should be used.<br><br>By default, <B>dos2unix</B> converts files <B>in-place</B>. This means the original file is overwritten. It is highly recommended to use the <B>-s</B> (suffix) option to create a backup or the <B>-o</B> (newfile) option to output to a separate file, especially for critical data.


title: STANDARD INPUT/OUTPUT USAGE
content:
When no <I>FILE</I> argument is provided, <B>dos2unix</B> reads from standard input (<B>stdin</B>) and writes to standard output (<B>stdout</B>). This allows it to be integrated into pipelines, for example: <br><I>cat input.txt | dos2unix > output.txt</I>


title: PROCESSING MULTIPLE FILES
content:
You can provide multiple file paths as arguments to <B>dos2unix</B> to convert them all in a single command. Wildcards can also be used, for example: <br><I>dos2unix *.txt</I> <br>This will convert all files ending with <B>.txt</B> in the current directory, in-place.


title: HISTORY
content:
The <B>dos2unix</B> utility, along with its counterpart <B>unix2dos</B>, has been a staple in <I>Unix</I>-like operating systems for decades. Its existence reflects the historical divergence in text file conventions across different computing platforms, particularly between <I>Unix</I>/<I>Linux</I> and <I>Microsoft DOS</I>/<I>Windows</I>.<br><br>Originally developed to address cross-platform compatibility issues in file transfers and scripting, it became an essential tool for developers and system administrators working in heterogeneous environments. The command's simplicity and singular focus on line ending conversion have ensured its enduring relevance, making it a widely adopted and stable component of most <I>Linux</I> distributions.


title: PARAMETERS
content:
<b><b>-T</b><i>format</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the output format. Common formats include png, svg, pdf, ps, dot, jpg, gif, etc.</I><br><br><b><b>-o</b><i>outfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Writes the generated graph to the specified output file. If omitted, output goes to standard output.</I><br><br><b><b>-K</b><i>layout</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the layout algorithm to use. Although dot itself defaults to 'dot', other layout engines like 'neato', 'fdp', 'sfdp', 'circo', 'twopi' can be explicitly chosen if the Graphviz suite is installed.</I><br><br><b><b>-G</b><i>name</i>=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sets a global graph attribute. Can be specified multiple times.</I><br><br><b><b>-N</b><i>name</i>=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sets a default node attribute. Can be specified multiple times.</I><br><br><b><b>-E</b><i>name</i>=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sets a default edge attribute. Can be specified multiple times.</I><br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints version information and exits.</I><br><br><b><b>-?</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints usage information and exits.</I><br><br><b><i>input_file(s)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>One or more input files containing graph descriptions in DOT language. If no files are specified, dot reads from standard input.</I><br><br>


title: DESCRIPTION
content:
<i><b>dot</b> is a powerful command-line tool from the open-source Graphviz suite, primarily used for laying out and rendering directed graphs. It interprets graph descriptions written in the plain-text <I>DOT language</I>, transforming them into high-quality graphical representations. Its strength lies in its hierarchical layout algorithm, which effectively visualizes dependencies, flowcharts, state machines, and organizational structures by arranging nodes in layers. Users define nodes, edges, and various attributes (colors, shapes, labels, sizes) within the DOT file, and <b>dot</b> automatically calculates optimal positions and edge routes. This automation makes it invaluable for generating visual diagrams from structured data, widely used in software engineering, bioinformatics, network visualization, and academic research. It supports a vast array of output formats, including common image types like PNG, SVG, PDF, and PostScript, allowing for diverse application integration.</i>


title: CAVEATS
content:
<I>Performance can degrade significantly for very large or dense graphs, potentially leading to long processing times or excessive memory usage.</I><br><I>The layout quality heavily depends on the structure of the input graph and the judicious use of DOT language attributes.</I><br><I>Errors in the DOT input file can lead to parsing failures or unexpected output.</I>


title: INPUT FORMAT: DOT LANGUAGE
content:
<i><code>dot</code> expects its input in the <I>DOT language</I>, a simple plain-text graph description language. It allows users to define nodes, edges (directed or undirected), and attach various attributes (like color, shape, label, font, size) to control the visual representation of the graph elements and the overall layout.</i>


title: OUTPUT FORMATS
content:
<i><code>dot</code> supports a wide range of output formats, making it versatile for different applications. These include raster images (PNG, JPEG, GIF), vector graphics (SVG, PDF, PostScript, EPS), and even other graph description languages (like plain DOT itself for debugging or further processing).</i>


title: HISTORY
content:
<I><code>dot</code> is a foundational component of Graphviz (Graph Visualization Software), an open-source graph drawing software package.</I><br><I>Graphviz was originally developed at AT&T Labs Research by Stephen North and others.</I><br><I>It originated in the 1990s as a set of tools for visualizing graphs that arose in various research projects.</I><br><I>The DOT language and the <code>dot</code> layout engine became key components, enabling programmatic graph drawing and widespread adoption in various fields from software engineering to bioinformatics.</I>


title: PARAMETERS
content:
<b><i><code>path</code></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file or resource to be locked. The actual lock file will typically be created with a '.lock' suffix or as '.&lt;pid&gt;' within the same directory.<br><br><b><b><code>-r</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Release or remove the lock file associated with the specified <i><code>path</code></i>. If the lock is not held by the current process or doesn't exist, it may exit with an error or do nothing.<br><br>


title: DESCRIPTION
content:
<b><code>dotlockfile</code></b> is a utility designed to create and manage "dot-lock" files, a common mechanism for implementing mutual exclusion (locking) on Unix-like file systems. It ensures that only one process can acquire a lock on a specific resource at a time, preventing race conditions and data corruption. This method is particularly crucial in environments where multiple processes might concurrently access shared files, such as mail spool directories or temporary file locations.<br><br>The "dot-lock" principle involves creating a unique temporary file (e.g., named with a process ID) and then atomically renaming it to a well-known lock file (e.g., <i><code>.filename.lock</code></i>). This atomic operation ensures that if the rename succeeds, the process has acquired the lock exclusively. If it fails, another process already holds the lock. <b><code>dotlockfile</code></b> abstracts these steps, making it easier for scripts and applications to implement robust file locking. It is often used in conjunction with mail delivery agents (MDAs) like <i>procmail</i> to lock mailboxes during delivery.


title: CAVEATS
content:
Not all Linux distributions include <b><code>dotlockfile</code></b> as a standard utility; its availability may depend on installed packages (e.g., <i>procmail</i>). The effectiveness of dot-locking relies heavily on specific filesystem semantics, particularly the atomicity of <i>rename(2)</i> and <i>link(2)</i> operations, which can vary across network file systems (NFS). Stale lock files (locks left behind by crashed processes) can occur, requiring manual intervention or a timeout mechanism (which <b><code>dotlockfile</code></b> itself might not provide).


title: HOW DOT-LOCKING WORKS
content:
Dot-locking primarily relies on the atomic nature of the <i>rename(2)</i> system call on POSIX-compliant filesystems. To acquire a lock for a file <i><code>FOO</code></i>, a process first creates a uniquely named temporary file (e.g., <i><code>.&lt;pid&gt;.&lt;hostname&gt;</code></i>) in the same directory. It then attempts to atomically rename this temporary file to the intended lock file name (e.g., <i><code>.FOO.lock</code></i>). If the rename succeeds, the process has acquired the lock. If the rename fails (because the target lock file already exists), another process has already acquired the lock, and the current process must wait or retry. This mechanism ensures that only one process can successfully claim the lock at any given moment, even under heavy contention.


title: HISTORY
content:
The concept of 'dot-locking' originated in older Unix systems, particularly in the context of mail spool management (e.g., for <i>sendmail</i> and <i>procmail</i>) to prevent concurrent writes to user mailboxes. The <b><code>dotlockfile</code></b> utility, or scripts implementing similar logic, emerged as a robust way to ensure atomic acquisition of file locks in these shared environments. While more modern systems often rely on advisory locks (like <i>flock(2)</i> or <i>fcntl(2)</i>) or database-driven locking mechanisms, dot-locking remains a foundational concept, especially for simple, robust mutual exclusion on local filesystems.


title: SYNOPSIS
content:
<i>dotnet add</i> [<I>PROJECT</I>] <i>package &lt;PACKAGE_NAME&gt;</i> [<I>options</I>]<br><br><I>PROJECT</I>: The project file or directory to add the package to. If omitted, the command searches the current directory for a project file.<br><I>PACKAGE_NAME</I>: The name of the NuGet package to add.


title: PARAMETERS
content:
<b><PROJECT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the project file or directory to operate on. If not specified, the command searches the current directory.<br><br><b><PACKAGE_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the NuGet package to add.<br><br><b>--version <VERSION_SPEC></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the exact version of the package to add. If not provided, the latest stable version is used.<br><br><b>--framework <FRAMEWORK></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the package reference only when targeting a specific framework (e.g., 'net6.0', 'netcoreapp3.1').<br><br><b>--source <SOURCE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the NuGet package source URL to use during the restore operation. Can be a path or a URL.<br><br><b>--no-restore</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the implicit restore step after adding the package reference. Useful when managing multiple package additions before a single restore.<br><br><b>--interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the command to stop and wait for user input or action (e.g., for authentication).<br><br><b>--prerelease</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the latest prerelease version of the package to be added if no specific version is provided via --version.<br><br><b>--configfile <FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The NuGet configuration file (NuGet.Config) to use. If specified, only settings from this file will be used.<br><br>


title: DESCRIPTION
content:
The <b>dotnet add package</b> command provides a convenient way to add a NuGet package reference to a .NET project file. When executed, it inserts a <i>&lt;PackageReference&gt;</i> item into the specified project file (e.g., <i>.csproj</i>, <i>.fsproj</i>). By default, the command automatically resolves and adds the latest stable version of the specified package, and then performs a package restore operation to download and install its dependencies. This command streamlines the process of integrating external libraries and frameworks into your .NET applications, eliminating the need for manual project file editing. You can specify a particular package version, target a specific framework, or define a custom NuGet package source using its various options.


title: CAVEATS
content:
<i>This command modifies the project file (e.g., .csproj) directly.</i><br><i>It requires a valid .NET project file to operate. If no project is found in the current directory or specified, the command will fail.</i><br><i>By default, a package restore operation is performed, which might take time depending on network conditions and the number of dependencies. Use <b>--no-restore</b> to skip this step.</i><br><i>The command only adds &lt;PackageReference&gt; items; it does not manage global tools (use <b>dotnet tool install</b>) or local tools.</i><br><i>Version resolution defaults to the latest stable version. To add a prerelease version without specifying its exact number, use <b>--prerelease</b>.</i>


title: IMPLICIT RESTORE
content:
After adding a package reference, the command automatically performs a 'dotnet restore' operation to download the package and its dependencies. This ensures your project can immediately build and run with the new package. If you intend to add multiple packages in sequence, consider using the <b>--no-restore</b> option and then manually running <b>dotnet restore</b> once all packages have been added.


title: PROJECT FILE MODIFICATION
content:
This command modifies the specified project file (e.g., 'MyProject.csproj') by adding an <i>&lt;PackageReference Include="PackageName" Version="1.0.0" /&gt;</i> XML element. It handles the correct placement within the file, making manual XML editing unnecessary and less error-prone.


title: SPECIFYING FRAMEWORKS
content:
When developing multi-targeted applications, you can use the <b>--framework</b> option to add a package reference that is conditional on a specific target framework. For example, <b>dotnet add package MyLib --framework net6.0</b> will add the package only for the 'net6.0' target framework, allowing different versions or packages for other frameworks.


title: HISTORY
content:
The <b>dotnet add package</b> command is an integral part of the .NET Core CLI, which was introduced to streamline development workflows for .NET Core applications. It emerged as the primary command-line interface for managing NuGet package dependencies, replacing older methods like direct XML editing of <i>.csproj</i> files or reliance on third-party tools like Paket for this specific task. Its development focused on providing a consistent and intuitive experience for developers working across different operating systems, including Linux. It became particularly crucial with the shift from <i>project.json</i> to <i>.csproj</i> files for package management, offering a simple verb to interact with the new <i>&lt;PackageReference&gt;</i> format. Since its inception, it has been continually refined as part of the broader .NET SDK releases, ensuring compatibility with new .NET versions and features.


title: SEE ALSO
content:
dotnet restore (1), dotnet remove package (1), dotnet list package (1), dotnet build (1), dotnet publish (1), nuget (1)


title: SYNOPSIS
content:
dotnet add [<PROJECT>] reference <REFERENCE_PROJECT_PATH> [<REFERENCE_PROJECT_PATH>...] [options]<br><br>Where:<br><br><b>`PROJECT`</b><i> (optional)</i>: The path to the project file to add the reference to. If not specified, the command searches the current directory for a project file.<br><b>`REFERENCE_PROJECT_PATH`</b><i> (required)</i>: The path(s) to the project file(s) to be referenced. Multiple paths can be specified, separated by spaces.


title: PARAMETERS
content:
<b>PROJECT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> The path to the project file to add the reference to. If omitted, the command searches for a project file in the current working directory. This can be a project file (e.g., <i>MyProject.csproj</i>) or the directory containing it.<br><br><b>REFERENCE_PROJECT_PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required.</i> The path(s) to the project file(s) that should be added as a reference to the target project. Multiple paths can be provided, separated by spaces.<br><br><b>-f|--framework <FRAMEWORK_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the project reference conditionally, meaning it's only active when the target project is compiled against a specific target framework moniker (TFM), such as <i>net6.0</i> or <i>net7.0</i>.<br><br><b>-h|--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints out a short help message for the command.<br><br>


title: DESCRIPTION
content:
The <i>dotnet add reference</i> command is a core utility within the .NET command-line interface (CLI) that enables developers to establish project-to-project (P2P) dependencies. When working with multi-project solutions, it's common for one project (e.g., an application) to depend on another (e.g., a shared library). This command facilitates the addition of such a reference by modifying the target project's file (e.g., <i>.csproj</i>, <i>.fsproj</i>, or <i>.vbproj</i>). <br><br>Upon execution, <i>dotnet add reference</i> inserts a <i>&lt;ProjectReference&gt;</i> item into the project file, linking it to the specified referenced project. This ensures that during compilation, the dependent project can correctly resolve types and members from the referenced project. It also ensures that the referenced project is built before the dependent project, maintaining the correct build order. This command is particularly useful for managing dependencies within a solution, streamlining the development workflow by abstracting away manual XML editing of project files. It works seamlessly across various operating systems, including Linux, macOS, and Windows, as it's part of the cross-platform .NET SDK.


title: CAVEATS
content:
<br><b>Existing Projects Only:</b> The paths provided for `REFERENCE_PROJECT_PATH` must point to existing .NET project files (<i>.csproj</i>, <i>.fsproj</i>, <i>.vbproj</i>). The command will fail if the files do not exist.<br><b>Circular References:</b> Creating circular references between projects (e.g., Project A references Project B, and Project B references Project A) is not permitted and will result in build errors.<br><b>File Modification:</b> The command directly modifies the target project's XML file. It's advisable to commit your changes or be aware of the modifications if using version control.<br><b>Build Dependency:</b> Adding a project reference does not automatically build the referenced project. However, during a subsequent <i>dotnet build</i> of the dependent project, the referenced project will be implicitly built if it's outdated or part of the same solution.


title: PROJECT VS. PACKAGE REFERENCES
content:
It's important to distinguish between <i>project references</i> and <i>package references</i>. <i>dotnet add reference</i> is used for project-to-project dependencies within the same solution or codebase, where you are referencing another local source project. In contrast, <i>dotnet add package</i> is used for referencing external NuGet packages, which are pre-compiled libraries distributed via a package manager. Both serve to resolve dependencies, but their contexts and underlying mechanisms differ significantly.


title: EXAMPLE USAGE
content:
<br><b>1. Add a single project reference from the current directory:</b><br><i>dotnet add reference ../MySharedLibrary/MySharedLibrary.csproj</i><br><br><b>2. Add multiple project references to a specific project file:</b><br><i>dotnet add src/MyWebApp/MyWebApp.csproj reference ../MyDataLayer/MyDataLayer.csproj ../MyBusinessLogic/MyBusinessLogic.csproj</i><br><br><b>3. Add a project reference conditionally for a specific framework:</b><br><i>dotnet add reference ../MyLibrary/MyLibrary.csproj --framework net7.0</i>


title: HISTORY
content:
The `dotnet` CLI, including the `dotnet add reference` command, emerged with the introduction of .NET Core (now simply .NET) as a cross-platform and modular framework. Before the `dotnet` CLI, managing project references often involved direct manual editing of MSBuild <i>.csproj</i> files or reliance on IDE-specific functionalities (like Visual Studio). The `dotnet add reference` command was introduced to streamline and standardize the process of adding project-to-project dependencies for command-line driven development, providing a consistent experience across all supported operating systems, including Linux. It replaced the less structured `project.json` approach used in early .NET Core iterations, aligning with the return to MSBuild as the primary build system.


title: SYNOPSIS
content:
<I>dotnet build</I> [<I>&lt;PROJECT | SOLUTION&gt;</I>] [<I>options</I>]<br><br><I>&lt;PROJECT | SOLUTION&gt;</I>: Optional. The path to a project file, a solution file, or a directory containing either. If omitted, the command searches the current directory for a project or solution file.


title: PARAMETERS
content:
<b><b>-c | --configuration &lt;CONFIGURATION&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the build configuration, such as <I>Debug</I> (default) or <I>Release</I>.<br><br><b><b>-f | --framework &lt;FRAMEWORK&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compiles for a specific target framework defined in the project file, e.g., <I>net8.0</I> or <I>net7.0</I>.<br><br><b><b>-o | --output &lt;OUTPUT_DIRECTORY&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directory where the build artifacts are placed. Defaults to <I>bin/Debug</I> or <I>bin/Release</I> within the project directory.<br><br><b><b>--no-restore</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not perform an implicit NuGet restore during build. This option is useful when dependencies are already restored.<br><br><b><b>--no-dependencies</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not build project-to-project references. Only builds the specified project.<br><br><b><b>-r | --runtime &lt;RUNTIME_IDENTIFIER&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds a self-contained application for a specific runtime (RID), e.g., <I>linux-x64</I>, <I>win-x86</I>.<br><br><b><b>-p | --property &lt;PROPERTY=VALUE&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets one or more MSBuild properties. For example, <I>-p:Version=1.0.0</I>.<br><br><b><b>-v | --verbosity &lt;LEVEL&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the MSBuild verbosity level. Options include <I>q</I> (quiet), <I>m</I> (minimal), <I>n</I> (normal), <I>d</I> (detailed), and <I>diag</I> (diagnostic).<br><br>


title: DESCRIPTION
content:
The <I>dotnet build</I> command is a fundamental tool within the .NET Command-Line Interface (CLI), used to compile C#, F#, or VB.NET projects and solutions. It's the primary way to transform your source code into executable files (.exe) or libraries (.dll). When invoked, <I>dotnet build</I> implicitly performs a dependency restore (similar to <I>dotnet restore</I>) unless explicitly told not to, ensuring all necessary NuGet packages are available. It then orchestrates the compilation process, resolving references, compiling code, and packaging the output into the project's designated build output directory (typically <I>bin/Debug</I> or <I>bin/Release</I>). This command is crucial for validating code, preparing applications for testing, or as a step before publishing for deployment. It supports building for various target frameworks and runtimes, making it highly versatile for cross-platform development.


title: CAVEATS
content:
<ul><li>Requires the .NET SDK to be installed on the Linux system.</li><li>Build success is contingent upon valid project files (.csproj, .fsproj, .vbproj) and accessibility of all declared dependencies.</li><li>While executed on Linux, <I>dotnet build</I> can compile code targeting other operating systems or architectures when combined with the <b>--runtime</b> option.</li></ul>


title: IMPLICIT RESTORE
content:
Before compiling, <I>dotnet build</I> automatically executes a <I>dotnet restore</I> operation to download and install all project dependencies. This behavior can be bypassed using the <b>--no-restore</b> option if dependencies are already guaranteed to be in place.


title: BUILD ARTIFACTS LOCATION
content:
Compiled outputs (assemblies, executables, debug symbols) are typically placed in a subdirectory of the project's root, usually under <I>bin/&lt;Configuration&gt;/&lt;TargetFramework&gt;/</I>, for example, <I>bin/Debug/net8.0/</I>. This organized structure helps manage different build outputs.


title: HISTORY
content:
The <I>dotnet build</I> command emerged as a cornerstone of the .NET Core CLI, introduced around 2016. Its development was central to Microsoft's strategy to make .NET cross-platform and open-source, moving away from Windows-exclusive development environments like Visual Studio. It provided a unified, command-line driven interface for building .NET applications on Linux, macOS, and Windows, abstracting away the complexities of underlying build systems like MSBuild while still leveraging them. With each subsequent release of .NET (e.g., .NET 5, 6, 7, 8), <I>dotnet build</I> has continued to evolve, supporting new language features, target frameworks, and build optimizations, solidifying its role as the standard build command for modern .NET development.


title: SEE ALSO
content:
<I>dotnet</I>(1), <I>dotnet restore</I>(1), <I>dotnet run</I>(1), <I>dotnet publish</I>(1), <I>dotnet test</I>(1)


title: SYNOPSIS
content:
<b>dotnet publish</b> [<I>PROJECT | SOLUTION</I>] [<I>options</I>]<br><br>The <I>PROJECT | SOLUTION</I> argument can be a path to a project file, a solution file, or a directory containing a .NET project or solution. If omitted, the command searches for a project or solution file in the current directory.


title: PARAMETERS
content:
<b>--configuration | -c <CONFIGURATION></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the build configuration. Defaults to 'Debug' or 'Release' based on environment variables.<br><br><b>--framework | -f <FRAMEWORK></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Targets a specific framework, e.g., 'net8.0'.<br><br><b>--runtime | -r <RUNTIME_IDENTIFIER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Publishes the application for a specific runtime (OS and CPU architecture), e.g., 'linux-x64', 'win-x64', 'osx-arm64'.<br><br><b>--output | -o <OUTPUT_DIRECTORY></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output directory. If not specified, the output is placed in a default 'bin/[configuration]/[framework]/publish/' folder.<br><br><b>--self-contained [true|false]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Publishes the .NET runtime with the application, making it fully portable. Requires a Runtime Identifier (RID). Defaults to 'true' if an RID is specified, otherwise 'false'.<br><br><b>--no-build</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not build the project before publishing. The 'restore' step is skipped if 'no-build' is also specified.<br><br><b>--no-restore</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not restore NuGet packages before publishing.<br><br><b>--verbosity <LEVEL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the verbosity level of the command. Allowed levels are 'q[uiet]', 'm[inimal]', 'n[ormal]', 'd[etailed]', and 'diag[nostic]'.<br><br>


title: DESCRIPTION
content:
The <b>dotnet publish</b> command compiles the application, reads through its dependencies specified in the project file, and publishes the resulting set of files to a directory. This command is crucial for preparing a .NET application for deployment across various environments, including Linux, Windows, macOS, or Docker containers.<br><br>Unlike <b>dotnet build</b>, which primarily compiles the source code, <b>dotnet publish</b> goes a step further by collecting all the necessary components for deployment: the application's executable, its dependencies (libraries), configuration files, and static assets. The output can be either <i>framework-dependent</i>, requiring the target machine to have the .NET runtime installed, or <i>self-contained</i>, where the .NET runtime and framework libraries are bundled with the application, making it fully portable.


title: CAVEATS
content:
When publishing self-contained applications, the resulting deployment package can be significantly larger due to the bundled .NET runtime and framework libraries. Ensure sufficient disk space on the target system.<br><br>Cross-platform publishing requires specifying a correct <I>Runtime Identifier (RID)</I> for the target environment. Publishing for one platform (e.g., Windows) and trying to run on another (e.g., Linux) without the correct RID will fail unless it's a framework-dependent deployment with the correct runtime installed on the target.


title: DEPLOYMENT TYPES
content:
<b>dotnet publish</b> supports two primary deployment types:<br><ul><li><I>Framework-Dependent Deployment (FDD)</I>: Creates a smaller deployment where the application relies on a globally installed .NET runtime on the target machine.</li><li><I>Self-Contained Deployment (SCD)</I>: Includes the .NET runtime and framework libraries with the application, making it fully portable but larger in size. This is often preferred for environments where the .NET runtime might not be pre-installed or where specific runtime versions are required.</li></ul>


title: RUNTIME IDENTIFIERS (RIDS)
content:
RIDs are crucial for targeting specific operating systems and CPU architectures (e.g., <I>linux-x64</I>, <I>win-arm64</I>, <I>osx-x64</I>). When using the <b>--runtime</b> option with <b>dotnet publish</b>, you are instructing the CLI to package your application specifically for that target environment, including its native dependencies. This is essential for self-contained deployments and for any scenario involving platform-specific native code.


title: PUBLISHING FOR DOCKER
content:
<b>dotnet publish</b> is widely used in Docker build processes. Typically, a multi-stage Dockerfile will use a build stage to publish the application, often using a specific RID (e.g., <I>linux-x64</I>), and then copy the published output into a smaller runtime image. This ensures that the final Docker image contains only the necessary application files and runtime components, minimizing image size.


title: HISTORY
content:
The <b>dotnet publish</b> command has been a fundamental part of the .NET CLI (Command Line Interface) since the early days of .NET Core, designed to facilitate cross-platform application deployment. It has evolved alongside the .NET ecosystem, adapting to new runtime versions, deployment models (like AOT compilation), and target environments, consistently serving as the primary method for preparing .NET applications for distribution.


title: PARAMETERS
content:
<b>[PROJECT_OR_SOLUTION]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional path to the project or solution file to restore. If not specified, the current directory is searched for a project or solution file.<br><br><b>-s | --source <SOURCE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a NuGet package source to use during the restore operation. Can be specified multiple times.<br><br><b>--packages <PACKAGES_DIRECTORY></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory where restored packages are placed. If not specified, the default global packages folder is used.<br><br><b>--configfile <FILE_PATH></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The NuGet configuration (nuget.config) file to use. If specified, only the settings from this file will be used.<br><br><b>-r | --runtime <RUNTIME_IDENTIFIER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a runtime for which to restore packages. This is used when restoring platform-specific packages.<br><br><b>--disable-parallel</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables restoring packages in parallel. Useful for troubleshooting.<br><br><b>--no-dependencies</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When restoring a project with project-to-project (P2P) references, restores only the root project, not its P2P references.<br><br><b>--interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the command to stop and wait for user input or authentication. Useful for protected feeds.<br><br><b>--force-evaluate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces restore to re-evaluate all dependencies even if a lock file exists. This can ensure the latest compatible versions are resolved.<br><br><b>--no-cache</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents restore from using HTTP cached packages. Forces a fresh download.<br><br><b>--ignore-failed-sources</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only warn about failed sources if there are packages that satisfy the version requirement from another source.<br><br><b>--verbosity <LEVEL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the verbosity level of the command. Allowed values are <I>q[uiet]</I>, <I>m[inimal]</I>, <I>n[ormal]</I>, <I>d[etailed]</I>, and <I>diag[nostic]</I>.<br><br><b>-h | --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints out a short help for the command.<br><br>


title: DESCRIPTION
content:
The <I>dotnet restore</I> command downloads all the necessary dependencies and tools for a .NET project or solution file. It's crucial for building, running, and publishing .NET applications, as it ensures all required NuGet packages are available locally.<br>When executed, <I>dotnet restore</I> analyzes the project's dependencies, typically defined in the <I>.csproj</I>, <I>.fsproj</I>, or <I>.vbproj</I> file, and then fetches them from configured NuGet package sources (like nuget.org or private feeds). It populates the <I>project.assets.json</I> file, which contains information about the resolved packages, their versions, and their locations, effectively acting as a dependency graph. This command is often run implicitly by other commands like <I>dotnet build</I>, <I>dotnet run</I>, and <I>dotnet publish</I>, but can be executed explicitly to pre-fetch packages, especially in CI/CD environments or when troubleshooting dependency issues. It plays a vital role in enabling reproducible builds across different machines.


title: CAVEATS
content:
*   Requires the .NET SDK to be installed on the Linux system.<br>*   Internet connectivity is generally required to download packages from remote NuGet sources.<br>*   The <I>project.assets.json</I> file, generated by restore, should not be manually edited and is typically excluded from source control.<br>*   Large projects with many dependencies can take significant time and consume bandwidth.<br>*   Package sources must be configured correctly, either globally via <I>nuget.config</I> or per-project.


title: <I>WHEN TO USE IT</I>
content:
While <I>dotnet restore</I> is often implicitly called by commands like <I>dotnet build</I> or <I>dotnet run</I>, explicitly running it is beneficial in several scenarios:<br>*   <I>CI/CD Pipelines</I>: To ensure all dependencies are downloaded before a build step, allowing the build step to run offline or faster.<br>*   <I>Troubleshooting</I>: To diagnose dependency resolution issues by observing its output directly.<br>*   <I>Pre-fetching</I>: To download all packages upfront, especially before working offline or when network conditions might be unstable.<br>*   <I>Lock File Generation</I>: To update or generate the <I>project.assets.json</I> file explicitly.


title: <I>IMPLICIT RESTORE</I>
content:
The .NET SDK 6.0 and later versions enable implicit restore for most commands that require it. This means you typically don't need to run <I>dotnet restore</I> explicitly before <I>dotnet build</I>, <I>dotnet run</I>, <I>dotnet test</I>, or <I>dotnet publish</I>. However, it's good practice to understand its function and when explicit execution might be necessary.


title: HISTORY
content:
The <I>dotnet restore</I> command became a cornerstone of the .NET Core (now just .NET) ecosystem, evolving from the previous <I>NuGet restore</I> command used in earlier .NET Framework projects. With the introduction of .NET Core, the <I>dotnet CLI</I> (Command-Line Interface) became the primary interface for managing .NET projects across platforms, including Linux. <I>dotnet restore</I> was integrated into the CLI to streamline the dependency management workflow, making cross-platform development more consistent and efficient. Its design focused on performance improvements and better integration with build systems compared to its predecessors. It's a fundamental step in the modern .NET development lifecycle.


title: SYNOPSIS
content:
<b>dotnet run</b> [<I>options</I>] [<I>project</I> | <I>solution</I> | <I>directory</I>] [<I>--</I> <I>application-arguments</I>]


title: PARAMETERS
content:
<b><b>--project</b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the project file (e.g., <i>.csproj</i>, <i>.fsproj</i>), solution file (<i>.sln</i>), or directory containing the project to run. If omitted, <b>dotnet run</b> searches the current directory.<br><br><b><b>--no-build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the implicit build step before running. Requires the project to be already built.<br><br><b><b>--configuration</b> <I>CONFIG</I> | <b>-c</b> <I>CONFIG</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the build configuration. Common values are <i>Debug</i> (default) or <i>Release</i>.<br><br><b><b>--framework</b> <I>FRAMEWORK_ID</I> | <b>-f</b> <I>FRAMEWORK_ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the application for a specific target framework defined in the project file (e.g., <i>net8.0</i>).<br><br><b><b>--runtime</b> <I>RUNTIME_IDENTIFIER</I> | <b>-r</b> <I>RUNTIME_IDENTIFIER</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target runtime to run the application (e.g., <i>linux-x64</i>).<br><br><b><b>--launch-profile</b> <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a named launch profile from <i>launchSettings.json</i> to set environment variables or command-line arguments.<br><br><b><b>--no-launch-profile</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the <i>launchSettings.json</i> file from being loaded, ignoring any launch profiles.<br><br><b><b>--verbosity</b> <I>LEVEL</I> | <b>-v</b> <I>LEVEL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the verbosity level of the command. Possible levels include <i>q[uiet]</i>, <i>m[inimal]</i>, <i>n[ormal]</i>, <i>d[etailed]</i>, and <i>diag[nostic]</i>.<br><br><b><b>--property</b> <I>PROPERTY</I> | <b>-p</b> <I>PROPERTY</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or overrides one or more MSBuild properties.<br><br><b><b>--</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A separator used to pass arguments directly to the application being run. All arguments following <b>--</b> are treated as application arguments, not <b>dotnet run</b> options.<br><br>


title: DESCRIPTION
content:
<b>dotnet run</b> is a fundamental command within the .NET Command Line Interface (CLI) that provides a convenient way to compile and execute a .NET application directly from its source code. It's primarily used during the development and testing phases of an application, offering a quick feedback loop without needing to manually build, publish, and then launch the resulting executable or DLL.<br><br>When invoked, <b>dotnet run</b> first implicitly performs a <b>dotnet build</b> operation on the specified project (or the current directory's project if none is specified). This ensures that the latest source code changes are compiled into an executable or DLL. Once the build is successful, the command then proceeds to execute the compiled output.<br><br>This command abstracts away the complexities of locating the built assembly and invoking the correct runtime, making it exceptionally user-friendly for developers. It simplifies the workflow by integrating the build and run steps into a single command, ideal for rapid prototyping, debugging, and iterative development cycles on Linux and other platforms. You can also pass arguments directly to your application using a special separator.


title: CAVEATS
content:
<ul><li><b>Development Tool</b>: Primarily intended for development and testing. For production deployments, <b>dotnet publish</b> followed by direct execution is recommended.</li><li><b>Implicit Build</b>: The implicit build can sometimes mask underlying build errors if not paying close attention to the output.</li><li><b>SDK Requirement</b>: Requires the .NET SDK to be installed on the system, not just the runtime.</li><li><b>Performance</b>: Includes a build step, which can add overhead compared to directly executing an already published application.</li></ul>


title: PASSING ARGUMENTS TO THE APPLICATION
content:
One of the most common uses of <b>dotnet run</b> is to pass arguments directly to the application. This is achieved using the special <b>--</b> separator. All text after <b>--</b> on the command line is passed as command-line arguments to the executed .NET application, rather than being interpreted as options for <b>dotnet run</b> itself. For example, <i>dotnet run -- --environment Production --port 8080</i> would pass <i>--environment Production</i> and <i>--port 8080</i> to your application.


title: INTEGRATION WITH LAUNCHSETTINGS.JSON
content:
For ASP.NET Core and other web applications, <b>dotnet run</b> can optionally leverage launch profiles defined in <i>Properties/launchSettings.json</i>. These profiles allow you to configure environment variables, application arguments, and other settings for different execution scenarios (e.g., running with IIS Express, Kestrel, or Docker). By default, <b>dotnet run</b> will try to use the first suitable launch profile unless <b>--no-launch-profile</b> is specified or a specific profile is chosen with <b>--launch-profile <I>NAME</I></b>.


title: HISTORY
content:
The <b>dotnet run</b> command was introduced as a core part of the initial .NET Core CLI, which began gaining prominence around 2016 with the release of .NET Core 1.0. Its design philosophy was to provide a simplified, cross-platform development experience by integrating common build and run tasks. Over subsequent versions of .NET Core and later .NET 5+, <b>dotnet run</b> has remained a steadfast and heavily used command, evolving primarily through additional options and deeper integration with features like launch profiles, but its fundamental purpose as a convenient development tool has remained consistent.


title: SEE ALSO
content:
dotnet build(1), dotnet publish(1), dotnet restore(1), dotnet clean(1), dotnet new(1), dotnet exec(1)


title: SYNOPSIS
content:
<b>dotnet</b> <b>test</b> [<PROJECT> | <SOLUTION> | <DIRECTORY>] [options] [--- <VSTEST_OPTIONS>]<br><br>Where:<br>  <b><PROJECT></b> | <b><SOLUTION></b> | <b><DIRECTORY></b>: Specifies the path to a .NET project file, a solution file, or a directory containing a project or solution. If omitted, the command searches the current directory for a project or solution file.<br>  <b>[options]</b>: Represents various command-line options that modify the behavior of the test run.<br>  <b>[--- <VSTEST_OPTIONS>]</b>: A special syntax to pass arbitrary arguments directly to the underlying <i>vstest.console.exe</i> test runner.


title: PARAMETERS
content:
<b><b>-h</b> | <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information and a list of available options for the <b>dotnet test</b> command.<br><br><b><b>-c</b> | <b>--configuration</b> <CONFIGURATION></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the build configuration for the tests, such as <b>Debug</b> (default) or <b>Release</b>.<br><br><b><b>--no-build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not build the test project before running tests. This option is useful when tests have already been built manually.<br><br><b><b>--no-restore</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not perform an implicit NuGet package restore during command execution. Requires packages to be restored manually beforehand (e.g., with <b>dotnet restore</b>).<br><br><b><b>-f</b> | <b>--framework</b> <FRAMEWORK_IDENTIFIER></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target framework moniker (TFM) for which to run tests (e.g., <b>net6.0</b>, <b>net8.0</b>). Tests will only be run for this specific framework.<br><br><b><b>--filter</b> <EXPRESSION></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters tests based on a given expression. Expressions can use properties like <i>FullyQualifiedName</i>, <i>DisplayName</i>, <i>Category</i>. Example: <b>Category=SmokeTests</b> or <b>FullyQualifiedName~MyNamespace.MyClass</b>.<br><br><b><b>--logger</b> <LOGGER_URI/NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a logger for test results. Common loggers include <b>trx</b> (for VSTest TRX format) and <b>console</b>. Example: <b>trx;LogFileName=test_results.trx</b> to generate a TRX report.<br><br><b><b>-o</b> | <b>--output</b> <DIRECTORY></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The directory in which to find the binaries to run. If not specified, the command will look for the binaries in the default build output location.<br><br><b><b>--results-directory</b> <DIRECTORY></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The directory where test results files (e.g., TRX reports) will be placed. Defaults to a <b>TestResults</b> subdirectory within the project's directory.<br><br><b><b>--verbosity</b> <LEVEL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the verbosity level of logging during the test run. Allowed values are <i>quiet</i>, <i>minimal</i>, <i>normal</i>, <i>detailed</i>, and <i>diagnostic</i>.<br><br><b><b>--collect</b> <DATA_COLLECTOR_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a data collector for the test run. A common use case is <b>Coverage</b> to collect code coverage information.<br><br><b><b>--nologo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not display the Microsoft Test Platform banner and copyright message.<br><br><b><b>--settings</b> <SETTINGS_FILE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the <i>.runsettings</i> file to use for configuring the test run. This file can specify data collectors, test run parameters, and more.<br><br><b><b>---</b> <VSTEST_OPTIONS></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes additional, unparsed arguments directly to the underlying <i>vstest.console.exe</i> executable. This allows for fine-grained control over the test execution engine.<br><br>


title: DESCRIPTION
content:
The <b>dotnet test</b> command is an essential part of the .NET Command-Line Interface (CLI), designed to <i>execute</i> unit tests within a .NET project or solution. It is used extensively by developers to ensure the quality and correctness of their codebases. <br><br>When invoked, <b>dotnet test</b> first attempts to build the specified project or solution if necessary. It then discovers tests using registered <i>test adapters</i> for popular frameworks like <i>xUnit.NET</i>, <i>NUnit</i>, and <i>MSTest</i>. Once tests are discovered, it executes them and reports the outcomes, including passed, failed, and skipped tests. <br><br>The command offers a rich set of options for customizing test runs, such as filtering tests by name or category, specifying build configurations, selecting target frameworks, and configuring loggers for detailed test results. It plays a crucial role in automated testing and continuous integration/continuous delivery (CI/CD) pipelines, enabling rapid feedback on code changes.


title: CAVEATS
content:
While powerful, <b>dotnet test</b> has a few considerations:<br>  <i><b>.NET SDK Dependency</b></i>: It requires a compatible .NET SDK to be installed on the system to function.<br>  <i><b>Test Adapter Requirement</b></i>: To run tests from specific frameworks (e.g., xUnit, NUnit, MSTest), the corresponding <i>test adapter</i> NuGet package must be referenced in the test project.<br>  <i><b>Cross-Platform Nuances</b></i>: Although cross-platform, some underlying tools and path conventions might behave slightly differently between Linux, Windows, and macOS.<br>  <i><b>Performance</b></i>: For very large test suites or complex projects, test execution can be time-consuming. Utilizing options like <b>--no-build</b>, <b>--filter</b>, or parallel test execution (if supported by the test runner) can help mitigate this.


title: EXAMPLE USAGE
content:
To run all tests in the current directory's project and generate a TRX report:<br>  <b>dotnet test --logger trx</b><br><br>To run tests from a specific project file with a filter:<br>  <b>dotnet test MyProject.Tests.csproj --filter 'Category=SmokeTests'</b><br><br>To run tests in Release configuration without rebuilding:<br>  <b>dotnet test --configuration Release --no-build</b>


