docs: akka CLI docs (#32)

Co-authored-by: GitHub <[email protected]>

Makefile

@@ -44,7 +44,7 @@ attributes: prepare
 		> "${managed_partials}/attributes.adoc"
 	docs/bin/version.sh | xargs -0  printf ":akka-javasdk-version: %s" \
 		> "${managed_partials}/attributes.adoc"
-	echo ":akka-cli-version: 3.0.5"     >> "${managed_partials}/attributes.adoc"
+	echo ":akka-cli-version: 3.0.6"     >> "${managed_partials}/attributes.adoc"
 	echo ":akka-cli-min-version: 3.0.4" >> "${managed_partials}/attributes.adoc"
 	# see https://adoptium.net/marketplace/
 	echo ":java-version: 21" \

docs/src/modules/reference/pages/cli/akka-cli/akka.adoc

@@ -26,21 +26,21 @@ Welcome to the Akka CLI, for more information on its usage please visit the docu
 
 * link:akka_auth.html[akka auth]	 - Manage Akka authentication.
 * link:akka_completion.html[akka completion]	 - Generate shell completion scripts
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
-* link:akka_container-registry.html[akka container-registry]	 - Manage the Akka Container Registry.
-* link:akka_docker.html[akka docker]	 - Manage Docker credentials for Akka projects.
-* link:akka_docs.html[akka docs]	 - Opens the Akka documentation page
-* link:akka_local.html[akka local]	 - Helps with local development.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
+* link:akka_container-registry.html[akka container-registry]	 - Manage and push service images to the Akka Container Registry.
+* link:akka_docker.html[akka docker]	 - Manage credentials for projects using private Docker registries.
+* link:akka_docs.html[akka docs]	 - Open the Akka documentation page
+* link:akka_local.html[akka local]	 - Interact with and manage Akka services running locally.
 * link:akka_logs.html[akka logs]	 - Display the last few lines of logs for a specific service.
 * link:akka_organizations.html[akka organizations]	 - Manage your organizations on Akka
 * link:akka_projects.html[akka projects]	 - Manage your Akka projects.
 * link:akka_quickstart.html[akka quickstart]	 - Akka quickstart project samples.
-* link:akka_regions.html[akka regions]	 - Manage regions on Akka
+* link:akka_regions.html[akka regions]	 - Manage available regions.
 * link:akka_roles.html[akka roles]	 - Manage the user roles for an Akka project.
 * link:akka_routes.html[akka routes]	 - Manage routes for your Akka project.
 * link:akka_secrets.html[akka secrets]	 - Manage secrets for an Akka project.
 * link:akka_services.html[akka services]	 - Manage and deploy services on Akka.
-* link:akka_version.html[akka version]	 - Prints the akka version
+* link:akka_version.html[akka version]	 - Print the akka CLI version
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth.adoc

@@ -31,12 +31,12 @@ When authorized, you can use the CLI to perform the same operations available in
 == SEE ALSO
 
 * link:akka.html[akka]	 - Akka control
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 * link:akka_auth_current-login.html[akka auth current-login]	 - Get details for the current logged in user.
 * link:akka_auth_login.html[akka auth login]	 - Log in to Akka.
 * link:akka_auth_logout.html[akka auth logout]	 - Log out the current user.
-* link:akka_auth_signup.html[akka auth signup]	 - Opens the registration page.
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_signup.html[akka auth signup]	 - Open the registration page.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 * link:akka_auth_use-token.html[akka auth use-token]	 - Login using a token.
 
 [discrete]

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry.adoc

@@ -1,10 +1,14 @@
 = akka auth container-registry
 
-Manage the Akka Container Registry configuration.
+Manage configuration for Akka Container Registry.
 
 == Synopsis
 
-The Akka Container Registry (ACR) can be used by all Akka users to deploy services and is available in all Akka regions.
+The Akka Container Registry (ACR) can be used by all users to deploy their services.
+ACR uses an access token generated via Akka for authentication.
+This command allows you to configure the Docker credential helper for ACR.
+
+NOTE: to use this command, the current user must be logged into Akka and Docker must be installed and accessible for the current user.
 
 == Options
 
@@ -32,8 +36,8 @@ The Akka Container Registry (ACR) can be used by all Akka users to deploy servic
 * link:akka_auth.html[akka auth]	 - Manage Akka authentication.
 * link:akka_auth_container-registry_clear-cached-token.html[akka auth container-registry clear-cached-token]	 - Clear the cached Akka Container Registry access token.
 * link:akka_auth_container-registry_configure.html[akka auth container-registry configure]	 - Configure the Akka Container Registry docker credential helper.
-* link:akka_auth_container-registry_credentials.html[akka auth container-registry credentials]	 - Retrieves an Akka Container Registry access token for the current user.
-* link:akka_auth_container-registry_install-helper.html[akka auth container-registry install-helper]	 - Installs the Akka Docker credential helper in the selected directory.
+* link:akka_auth_container-registry_credentials.html[akka auth container-registry credentials]	 - Retrieve an Akka Container Registry access token for the current user.
+* link:akka_auth_container-registry_install-helper.html[akka auth container-registry install-helper]	 - Install the Akka Docker credential helper in the selected directory.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_clear-cached-token.adoc

@@ -31,7 +31,7 @@ akka auth container-registry clear-cached-token [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_configure.adoc

@@ -33,7 +33,7 @@ akka auth container-registry configure [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_credentials.adoc

@@ -1,6 +1,6 @@
 = akka auth container-registry credentials
 
-Retrieves an Akka Container Registry access token for the current user.
+Retrieve an Akka Container Registry access token for the current user.
 
 ----
 akka auth container-registry credentials [flags]
@@ -32,7 +32,7 @@ akka auth container-registry credentials [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_install-helper.adoc

@@ -1,6 +1,6 @@
 = akka auth container-registry install-helper
 
-Installs the Akka Docker credential helper in the selected directory.
+Install the Akka Docker credential helper in the selected directory.
 
 == Synopsis
 
@@ -33,7 +33,7 @@ akka auth container-registry install-helper [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_signup.adoc

@@ -1,6 +1,6 @@
 = akka auth signup
 
-Opens the registration page.
+Open the registration page.
 
 ----
 akka auth signup [flags]

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens.adoc

@@ -1,6 +1,10 @@
 = akka auth tokens
 
-Manage Akka authentication tokens.
+Manage Akka authentication tokens for your user.
+
+== Synopsis
+
+The command `akka auth tokens`  manage the authentication tokens for your user allowing you to revoke any token at any time, but also to create new tokens for use in CI/CD pipelines for machine-user accounts.
 
 == Options
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens_create.adoc

@@ -43,7 +43,7 @@ Token created: 0123456789abcdef0123456789abcdef0123456789abcdef
 
 == SEE ALSO
 
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens_list.adoc

@@ -35,7 +35,7 @@ akka auth tokens list [flags]
 
 == SEE ALSO
 
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens_revoke.adoc

@@ -37,7 +37,7 @@ akka auth tokens revoke ID [flags]
 
 == SEE ALSO
 
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config.adoc

@@ -1,10 +1,13 @@
 = akka config
 
-Manage the local Akka configuration.
+Manage configuration and context for the Akka CLI.
 
 == Synopsis
 
 The `akka config` commands display and set configuration contexts and values that apply to subsequent commands.
+These are often useful to make your CLI experience more fluid.
+For example, by having set a default _project_, you can avoid specifying the project id or name in every command.
+
 Configuration settings are stored in a file on your local system, by default at `.akka/config.yaml` in your home directory.
 This location can be adjusted with the `--config` flag.
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_clear-cache.adoc

@@ -33,7 +33,7 @@ akka config clear-cache [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_clear.adoc

@@ -33,7 +33,7 @@ akka config clear KEY [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_current-context.adoc

@@ -34,7 +34,7 @@ akka config current-context [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_delete-context.adoc

@@ -33,7 +33,7 @@ akka config delete-context CONTEXT [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_get-organization.adoc

@@ -29,7 +29,7 @@ akka config get-organization [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_get-project.adoc

@@ -29,7 +29,7 @@ akka config get-project [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_get.adoc

@@ -33,7 +33,7 @@ akka config get KEY [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_list-contexts.adoc

@@ -33,7 +33,7 @@ akka config list-contexts [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_list.adoc

@@ -33,7 +33,7 @@ akka config list [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_rename-context.adoc

@@ -33,7 +33,7 @@ akka config rename-context CONTEXT [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_set.adoc

@@ -37,7 +37,7 @@ akka config set KEY VALUE [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_config_use-context.adoc

@@ -37,7 +37,7 @@ akka config use-context CONTEXT [flags]
 
 == SEE ALSO
 
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_container-registry.adoc

@@ -1,10 +1,13 @@
 = akka container-registry
 
-Manage the Akka Container Registry.
+Manage and push service images to the Akka Container Registry.
 
 == Synopsis
 
-The Akka Container Registry (ACR) can be used by all Akka users to deploy services and is available in all Akka regions.
+The Akka Container Registry (ACR) can be used by all users to deploy their services.
+ACR makes service container images available to Akka in all regions automatically.
+
+NOTE: to use an external Docker registry instead, refer to the documentation https://doc.akka.io/operations/projects/external-container-registries.html .
 
 == Options
 
@@ -30,11 +33,11 @@ The Akka Container Registry (ACR) can be used by all Akka users to deploy servic
 == SEE ALSO
 
 * link:akka.html[akka]	 - Akka control
-* link:akka_container-registry_delete-image.html[akka container-registry delete-image]	 - delete image from the Akka Container Registry.
-If no tag is provided, it deletes all tags
+* link:akka_container-registry_delete-image.html[akka container-registry delete-image]	 - Delete image from the Akka Container Registry.
+If no tag is provided, it deletes all tags.
 * link:akka_container-registry_list.html[akka container-registry list]	 - List the Akka Container Registry and region.
 * link:akka_container-registry_list-images.html[akka container-registry list-images]	 - list images from the Akka Container Registry.
-* link:akka_container-registry_list-tags.html[akka container-registry list-tags]	 - list all images tags.
+* link:akka_container-registry_list-tags.html[akka container-registry list-tags]	 - List all images tags.
 * link:akka_container-registry_print.html[akka container-registry print]	 - Print the path of the Akka Container Registry.
 * link:akka_container-registry_push.html[akka container-registry push]	 - Push an Akka service image for a particular Akka project.
 

docs/src/modules/reference/pages/cli/akka-cli/akka_container-registry_delete-image.adoc

@@ -1,10 +1,10 @@
 = akka container-registry delete-image
 
-delete image from the Akka Container Registry.
-If no tag is provided, it deletes all tags
+Delete image from the Akka Container Registry.
+If no tag is provided, it deletes all tags.
 
 ----
-akka container-registry delete-image <image>[:<tag>] [flags]
+akka container-registry delete-image _image_[:<tag>] [flags]
 ----
 
 == Options
@@ -30,7 +30,7 @@ akka container-registry delete-image <image>[:<tag>] [flags]
 
 == SEE ALSO
 
-* link:akka_container-registry.html[akka container-registry]	 - Manage the Akka Container Registry.
+* link:akka_container-registry.html[akka container-registry]	 - Manage and push service images to the Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_container-registry_list-images.adoc

@@ -31,7 +31,7 @@ akka container-registry list-images [flags]
 
 == SEE ALSO
 
-* link:akka_container-registry.html[akka container-registry]	 - Manage the Akka Container Registry.
+* link:akka_container-registry.html[akka container-registry]	 - Manage and push service images to the Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_container-registry_list-tags.adoc

@@ -1,6 +1,6 @@
 = akka container-registry list-tags
 
-list all images tags.
+List all images tags.
 
 == Synopsis
 
@@ -35,7 +35,7 @@ akka container-registry list-tags IMAGE [flags]
 
 == SEE ALSO
 
-* link:akka_container-registry.html[akka container-registry]	 - Manage the Akka Container Registry.
+* link:akka_container-registry.html[akka container-registry]	 - Manage and push service images to the Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_container-registry_list.adoc

@@ -29,7 +29,7 @@ akka container-registry list [flags]
 
 == SEE ALSO
 
-* link:akka_container-registry.html[akka container-registry]	 - Manage the Akka Container Registry.
+* link:akka_container-registry.html[akka container-registry]	 - Manage and push service images to the Akka Container Registry.
 
 [discrete]