Merge pull request #6840 from vibhuanand/3064-context-use-docs

docs: clarify docker context use affects all terminal sessions

Author: thaJeztah

cli/command/context/use.go

@@ -13,7 +13,7 @@ import (
 func newUseCommand(dockerCLI command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "use CONTEXT",
-		Short: "Set the current docker context",
+		Short: "Set the default docker context",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			name := args[0]

docs/reference/commandline/context.md

@@ -15,7 +15,7 @@ Manage contexts
 | [`rm`](context_rm.md)           | Remove one or more contexts                                       |
 | [`show`](context_show.md)       | Print the name of the current context                             |
 | [`update`](context_update.md)   | Update a context                                                  |
-| [`use`](context_use.md)         | Set the current docker context                                    |
+| [`use`](context_use.md)         | Set the default docker context                                    |
 
 
 

docs/reference/commandline/context_use.md

@@ -1,13 +1,63 @@
 # context use
 
 <!---MARKER_GEN_START-->
-Set the current docker context
+Set the default docker context
 
 
 <!---MARKER_GEN_END-->
 
 ## Description
 
-Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment
-variables and `--host`, `--context` global options aren't set.
-To disable usage of contexts, you can use the special `default` context.
+The `docker context use` command sets the default context for the Docker CLI.
+
+The `docker context use` command sets the Docker CLI’s default context by updating
+your CLI config (`~/.docker/config.json`). This change is persistent, affecting
+all shells and sessions that share that config, not just the current terminal.
+
+For one-off commands or per-shell usage, use `--context` or the `DOCKER_CONTEXT`
+environment variable instead.
+
+## Examples
+
+### Set the default (sticky) context
+
+This updates the CLI configuration and applies to new terminal sessions:
+
+```bash
+$ docker context use my-context
+my-context
+
+$ docker context show
+my-context
+```
+
+### Use a context for a single command
+
+Use the global `--context` flag to avoid changing the default:
+
+```bash
+$ docker --context my-context ps
+```
+
+### Use a context for the current shell session
+
+Set `DOCKER_CONTEXT` to override the configured default in the current shell:
+
+```bash
+$ export DOCKER_CONTEXT=my-context
+$ docker context show
+my-context
+```
+
+To stop overriding:
+
+```bash
+$ unset DOCKER_CONTEXT
+```
+
+### Switch back to the default context
+
+```bash
+$ docker context use default
+default
+```