openshift · bergerhoffer · Feb 25, 2026 · ocpdocs-vale-bot · Feb 25, 2026
diff --git a/cli_reference/openshift_cli/administrator-cli-commands.adoc b/cli_reference/openshift_cli/administrator-cli-commands.adoc
@@ -6,9 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-This reference provides descriptions and example commands for OpenShift CLI (`oc`) administrator commands. You must have `cluster-admin` or equivalent permissions to use these commands.
+[role="_abstract"]
+To learn more about the {oc-first} administrator commands, review their descriptions and example commands. You must have `cluster-admin` or equivalent permissions to use these commands.
 
-For developer commands, see the xref:../../cli_reference/openshift_cli/developer-cli-commands.adoc#cli-developer-commands[OpenShift CLI developer command reference].
+For developer commands, see the "OpenShift CLI developer command reference".
 
 Run `oc adm -h` to list all administrator commands or run `oc <command> --help` to get additional details for a specific command.
 

diff --git a/cli_reference/openshift_cli/configuring-cli.adoc b/cli_reference/openshift_cli/configuring-cli.adoc
@@ -6,6 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
+TODO
+
+// TODO move this below to module? so small though. Maybe just consider removing the umbrella heading
 [id="cli-enabling-tab-completion"]
 == Enabling tab completion
 

diff --git a/cli_reference/openshift_cli/developer-cli-commands.adoc b/cli_reference/openshift_cli/developer-cli-commands.adoc
@@ -6,9 +6,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-This reference provides descriptions and example commands for OpenShift CLI (`oc`) developer commands.
+[role="_abstract"]
+To learn more about the {oc-first} developer commands, review their descriptions and example commands.
+
 ifdef::openshift-enterprise,openshift-origin[]
-For administrator commands, see the xref:../../cli_reference/openshift_cli/administrator-cli-commands.adoc#cli-administrator-commands[OpenShift CLI administrator command reference].
+For administrator commands, see the "OpenShift CLI administrator command reference".
 endif::openshift-enterprise,openshift-origin[]
 
 Run `oc help` to list all commands or run `oc <command> --help` to get additional details for a specific command.

diff --git a/cli_reference/openshift_cli/extending-cli-plugins.adoc b/cli_reference/openshift_cli/extending-cli-plugins.adoc
@@ -6,8 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can write and install plugins to build on the default `oc` commands,
-allowing you to perform new and more complex tasks with the
+[role="_abstract"]
+You can write and install plugins to build on the default `oc` commands, allowing you to perform new and more complex tasks with the
 ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 {product-title}
 endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

diff --git a/cli_reference/openshift_cli/managing-cli-profiles.adoc b/cli_reference/openshift_cli/managing-cli-profiles.adoc
@@ -6,18 +6,22 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-A CLI configuration file allows you to configure different profiles, or contexts, for use with the xref:../../cli_reference/index.adoc#cli-tools-overview[CLI tools overview]. A context consists of
-ifndef::microshift,openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
-xref:../../authentication/understanding-authentication.adoc#understanding-authentication[user authentication]
-endif::microshift,openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
-ifdef::microshift[]
-user authentication
-endif::[]
-a {product-title}
-server information associated with a _nickname_.
+[role="_abstract"]
+You can use a CLI configuration file to create different profiles, or contexts, for use with the {oc-first}. A context consists of user authentication and a {product-title} server information associated with a _nickname_.
 
 include::modules/about-cli-profiles-switch.adoc[leveloffset=+1]
 
-include::modules/manual-configuration-of-cli-profiles.adoc[leveloffset=+1]
+include::modules/manual-configuration-of-cli-profiles-example.adoc[leveloffset=+1]
+
+include::modules/manual-configuration-of-cli-profiles.adoc[leveloffset=+2]
 
 include::modules/load-and-merge-rules.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_managing-cli-profiles"]
+== Additional resources
+
+* xref:../../cli_reference/index.adoc#cli-tools-overview[CLI tools overview]
+ifndef::microshift,openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
+* xref:../../authentication/understanding-authentication.adoc#understanding-authentication[user authentication]
+endif::microshift,openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
diff --git a/modules/about-cli-profiles-switch.adoc b/modules/about-cli-profiles-switch.adoc
@@ -4,18 +4,18 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="about-switches-between-cli-profiles_{context}"]
-= About switches between CLI profiles
+= About switching between CLI profiles
 
-Contexts allow you to easily switch between multiple users across multiple {product-title} servers, or clusters, when using CLI operations. Nicknames make managing CLI configurations easier by providing short-hand references to contexts, user credentials, and cluster details.
-After a user logs in with the `oc` CLI for the first time,
-{product-title} creates a `~/.kube/config` file if one does not already exist. As more authentication and connection details are provided to the CLI, either automatically during an `oc login` operation or by manually configuring CLI profiles, the updated information is stored in the configuration file:
+[role="_abstract"]
+You can use contexts to easily switch between users across multiple {product-title} clusters when using the {oc-first}. You specify a nickname to make managing CLI configurations easier by providing short-hand references to contexts, user credentials, and cluster details.
 
-.CLI config file
+After a user logs in with the `oc` CLI for the first time, {product-title} creates a `~/.kube/config` file if one does not already exist. As more authentication and connection details are provided to the CLI, either automatically during an `oc login` operation or by manually configuring CLI profiles, the updated information is stored in the configuration file:
 
+.CLI configuration file
 [source,yaml]
 ----
 apiVersion: v1
-clusters: <1>
+clusters:
 - cluster:
     insecure-skip-tls-verify: true
     server: https://openshift1.example.com:8443
@@ -24,7 +24,7 @@ clusters: <1>
     insecure-skip-tls-verify: true
     server: https://openshift2.example.com:8443
   name: openshift2.example.com:8443
-contexts: <2>
+contexts:
 - context:
     cluster: openshift1.example.com:8443
     namespace: alice-project
@@ -35,25 +35,24 @@ contexts: <2>
     namespace: joe-project
     user: alice/openshift1.example.com:8443
   name: joe-project/openshift1/alice
-current-context: joe-project/openshift1.example.com:8443/alice <3>
+current-context: joe-project/openshift1.example.com:8443/alice
 kind: Config
 preferences: {}
 users: <4>
 - name: alice/openshift1.example.com:8443
   user:
     token: xZHd2piv5_9vQrg-SKXRJ2Dsl9SceNJdhNTljEKTb8k
 ----
+where:
 
-<1> The `clusters` section defines connection details for
-{product-title} clusters, including the address for their master server. In this example, one cluster is nicknamed `openshift1.example.com:8443` and another is nicknamed `openshift2.example.com:8443`.
-<2> This `contexts` section defines two contexts: one nicknamed `alice-project/openshift1.example.com:8443/alice`, using the `alice-project` project, `openshift1.example.com:8443` cluster, and `alice` user, and another nicknamed `joe-project/openshift1.example.com:8443/alice`, using the `joe-project` project, `openshift1.example.com:8443` cluster and `alice` user.
-<3> The `current-context` parameter shows that the `joe-project/openshift1.example.com:8443/alice` context is currently in use, allowing the `alice` user to work in the `joe-project` project on the `openshift1.example.com:8443` cluster.
-<4> The `users` section defines user credentials. In this example, the user nickname `alice/openshift1.example.com:8443` uses an access token.
+`clusters`:: Specifies connection details for {product-title} clusters, including the address for their master server. In this example, one cluster is nicknamed `openshift1.example.com:8443` and another is nicknamed `openshift2.example.com:8443`.
+`contexts`:: Specifies two contexts: one nicknamed `alice-project/openshift1.example.com:8443/alice`, using the `alice-project` project, `openshift1.example.com:8443` cluster, and `alice` user, and another nicknamed `joe-project/openshift1.example.com:8443/alice`, using the `joe-project` project, `openshift1.example.com:8443` cluster and `alice` user.
+`current-context`:: Specifies that the `joe-project/openshift1.example.com:8443/alice` context is currently in use, allowing the `alice` user to work in the `joe-project` project on the `openshift1.example.com:8443` cluster.
+`users`:: Specifies user credentials. In this example, the user nickname `alice/openshift1.example.com:8443` uses an access token.
 
 The CLI can support multiple configuration files which are loaded at runtime and merged together along with any override options specified from the command line. After you are logged in, you can use the `oc status` or `oc project` command to verify your current working environment:
 
 .Verify the current working environment
-
 [source,terminal,options="nowrap"]
 ----
 $ oc status
@@ -62,7 +61,6 @@ $ oc status
 .Example output
 [source,terminal]
 ----
-oc status
 In project Joe's Project (joe-project)
 
 service database (172.30.43.12:5434 -> 3306)
@@ -107,7 +105,7 @@ At any time, you can use the `oc config view` command to view your current CLI c
 
 [NOTE]
 ====
-If you have access to administrator credentials but are no longer logged in as the default system user `system:admin`, you can log back in as this user at any time as long as the credentials are still present in your CLI config file. The following command logs in and switches to the default project:
+If you have access to administrator credentials but are no longer logged in as the default system user `system:admin`, you can log back in as this user at any time as long as the credentials are still present in your CLI configuration file. The following command logs in and switches to the default project:
 
 [source,terminal]
 ----

diff --git a/modules/cli-configuring-kubeconfig-using-cli.adoc b/modules/cli-configuring-kubeconfig-using-cli.adoc
@@ -6,8 +6,14 @@
 [id="cli-accessing-kubeconfig-using-cli_{context}"]
 = Accessing kubeconfig by using the oc CLI
 
+[role="_abstract"]
 You can use the `oc` CLI to log in to your OpenShift cluster and retrieve a kubeconfig file for accessing the cluster from the command line.
 
+[IMPORTANT]
+====
+If you plan to reuse the exported `kubeconfig` file across sessions or machines, store it securely and avoid committing it to source control.
+====
+
 .Prerequisites
 
 * You have access to the {product-title} web console or API server endpoint.
@@ -18,12 +24,14 @@ You can use the `oc` CLI to log in to your OpenShift cluster and retrieve a kube
 +
 [source,terminal]
 ----
-$ oc login <api-server-url> -u <username> -p <password> <1><2><3>
+$ oc login <api_server_url> -u <username> -p <password>
 ----
 +
-<1> Specify the full API server URL. For example: `https://api.my-cluster.example.com:6443`.
-<2> Specify a valid username. For example: `kubeadmin`.
-<3> Provide the password for the specified user. For example, the `kubeadmin` password generated during cluster installation.
+where:
+
+`<api_server_url>`:: Specifies the full API server URL; for example, `https://api.my-cluster.example.com:6443`.
+`<username>`:: Specifies a valid username; for example, `kubeadmin`.
+`<password>`:: Specifies the password for the specified user; for example, the `kubeadmin` password generated during cluster installation.
 
 . Save the cluster configuration to a local file by running the following command:
 +
@@ -45,8 +53,3 @@ $ export KUBECONFIG=./kubeconfig
 ----
 $ oc get nodes
 ----
-
-[NOTE]
-====
-If you plan to reuse the exported `kubeconfig` file across sessions or machines, store it securely and avoid committing it to source control.
-====
diff --git a/modules/cli-extending-plugins-installing.adoc b/modules/cli-extending-plugins-installing.adoc
@@ -6,15 +6,15 @@
 [id="cli-installing-plugins_{context}"]
 = Installing and using CLI plugins
 
+[role="_abstract"]
 After you write a custom plugin for the
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 {product-title}
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 OpenShift
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
-CLI, you must install
-the plugin before use.
+CLI, you must install the plugin before use.
 
 .Prerequisites
 
@@ -50,19 +50,15 @@ The following compatible plugins are available:
 /usr/local/bin/<plugin_file>
 ----
 +
-If your plugin is not listed here, verify that the file begins with `oc-`
-or `kubectl-`, is executable, and is on your `PATH`.
+If your plugin is not listed here, verify that the file begins with `oc-` or `kubectl-`, is executable, and is on your `PATH`.
 . Invoke the new command or option introduced by the plugin.
 +
-For example, if you built and installed the `kubectl-ns` plugin from the
- link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository],
-  you can use the following command to view the current namespace.
+For example, if you built and installed the `kubectl-ns` plugin from the link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository], you can use the following command to view the current namespace.
 +
 [source,terminal]
 ----
 $ oc ns
 ----
 +
 Note that the command to invoke the plugin depends on the plugin file name.
-For example, a plugin with the file name of `oc-foo-bar` is invoked by the `oc foo bar`
-command.
+For example, a plugin with the file name of `oc-foo-bar` is invoked by the `oc foo bar` command.
diff --git a/modules/cli-extending-plugins-writing.adoc b/modules/cli-extending-plugins-writing.adoc
@@ -6,33 +6,27 @@
 [id="cli-writing-plugins_{context}"]
 = Writing CLI plugins
 
+[role="_abstract"]
 You can write a plugin for the
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 {product-title}
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 OpenShift
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
-CLI in any programming language
-or script that allows you to write command-line commands. Note that you can not
-use a plugin to overwrite an existing `oc` command.
+CLI in any programming language or script that allows you to write command-line commands. Note that you cannot use a plugin to overwrite an existing `oc` command.
 
-.Procedure
+This procedure creates a simple Bash plugin that prints a message to the terminal when the `oc foo` command is issued.
 
-This procedure creates a simple Bash plugin that prints a message to the
-terminal when the `oc foo` command is issued.
+.Procedure
 
 . Create a file called `oc-foo`.
 +
 When naming your plugin file, keep the following in mind:
 
 * The file must begin with `oc-` or `kubectl-` to be recognized as a
 plugin.
-* The file name determines the command that invokes the plugin. For example, a
-plugin with the file name `oc-foo-bar` can be invoked by a command of
-`oc foo bar`. You can also use underscores if you want the command to contain
-dashes. For example, a plugin with the file name `oc-foo_bar` can be invoked
-by a command of `oc foo-bar`.
+* The file name determines the command that invokes the plugin. For example, a plugin with the file name `oc-foo-bar` can be invoked by a command of `oc foo bar`. You can also use underscores if you want the command to contain dashes. For example, a plugin with the file name `oc-foo_bar` can be invoked by a command of `oc foo-bar`.
 
 . Add the following contents to the file.
 +
@@ -56,20 +50,18 @@ fi
 
 echo "I am a plugin named kubectl-foo"
 ----
-
++
 After you install this plugin for the
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 {product-title}
 endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-rosa-hcp[]
 OpenShift
 endif::openshift-rosa,openshift-rosa-hcp[]
-CLI, it can be invoked
-using the `oc foo` command.
+CLI, it can be invoked using the `oc foo` command.
 
 [role="_additional-resources"]
 .Additional resources
 
-* Review the link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository]
-for an example of a plugin written in Go.
-* Review the link:https://github.com/kubernetes/cli-runtime/[CLI runtime repository] for a set of utilities to assist in writing plugins in Go.
+* link:https://github.com/kubernetes/sample-cli-plugin[Sample plugin repository]
+* link:https://github.com/kubernetes/cli-runtime/[CLI runtime repository]
diff --git a/modules/load-and-merge-rules.adoc b/modules/load-and-merge-rules.adoc
@@ -6,9 +6,10 @@
 [id="load-and-merge-rules_{context}"]
 = Load and merge rules
 
-You can follow these rules, when issuing CLI operations for the loading and merging order for the CLI configuration:
+[role="_abstract"]
+Review the rules that {oc-first} uses for the loading and merging order for the CLI configuration.
 
-* CLI config files are retrieved from your workstation, using the following hierarchy and merge rules:
+* CLI configuration files are retrieved from your workstation, using the following hierarchy and merge rules:
 
 ** If the `--config` option is set, then only that file is loaded. The flag is set once and no merging takes place.
 ** If the `$KUBECONFIG` environment variable is set, then it is used. The variable can be a list of paths, and if so the paths are merged together. When a value is modified, it is modified in the file that defines the stanza. When a value is created, it is created in the first file that exists. If no files in the chain exist, then it creates the last file in the list.
@@ -17,7 +18,7 @@ You can follow these rules, when issuing CLI operations for the loading and merg
 * The context to use is determined based on the first match in the following flow:
 
 ** The value of the `--context` option.
-** The `current-context` value from the CLI config file.
+** The `current-context` value from the CLI configuration file.
 ** An empty value is allowed at this stage.
 
 * The user and cluster to use is determined. At this point, you may or may not have a context; they are built based on the first match in the following flow, which is run once for the user and once for the cluster:
@@ -33,7 +34,7 @@ cluster name.
 *** `--insecure-skip-tls-verify`
 ** If cluster information and a value for the attribute is present, then use it.
 ** If you do not have a server location, then there is an error.
-* The actual user information to use is determined. Users are built using the same rules as clusters, except that you can only have one authentication technique per user; conflicting techniques cause the operation to fail. Command-line options take precedence over config file values. Valid command-line options are:
+* The actual user information to use is determined. Users are built using the same rules as clusters, except that you can only have one authentication technique per user; conflicting techniques cause the operation to fail. Command-line options take precedence over configuration file values. Valid command-line options are:
 ** `--auth-path`
 ** `--client-certificate`
 ** `--client-key`