[Reference] freshness project: Profile (az account, az login)

src/azure-cli/azure/cli/command_modules/profile/_help.py

@@ -16,36 +16,49 @@
 
     To login with a service principal, specify --service-principal.
 examples:
-    - name: Log in interactively.
-      text: az login
-    - name: Log in with user name and password. This doesn't work with Microsoft accounts or accounts that have two-factor authentication enabled. Use -p=secret if the first character of the password is '-'.
-      text: az login -u [email protected] -p VerySecret
-    - name: Log in with a service principal using client secret. Use -p=secret if the first character of the password is '-'.
-      text: az login --service-principal -u http://azure-cli-2016-08-05-14-31-15 -p VerySecret --tenant contoso.onmicrosoft.com
-    - name: Log in with a service principal using client certificate.
-      text: az login --service-principal -u http://azure-cli-2016-08-05-14-31-15 -p ~/mycertfile.pem --tenant contoso.onmicrosoft.com
-    - name: Log in using a VM's system-assigned managed identity.
-      text: az login --identity
-    - name: Log in using a VM's user-assigned managed identity. Client or object ids of the service identity also work.
-      text: az login --identity -u /subscriptions/<subscriptionId>/resourcegroups/myRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID
+- name: Log in interactively.
+  text: az login
+- name: Log in with user name and password. This doesn't work with Microsoft accounts or accounts that have two-factor authentication enabled.
+  text: az login --user [email protected] --password VerySecret
+- name: Log in with a password containing a `-` as the first character.
+  text: az login --user [email protected] --password=-myPasswordThatStartsWithAdash
+- name: Log in with a service principal using a client secret.
+  text: az login --service-principal --user http://azure-cli-2016-08-05-14-31-15 --password VerySecret --tenant contoso.onmicrosoft.com
+- name: Log in with a service principal using a client certificate.
+  text: aaz login --service-principal --user http://azure-cli-2016-08-05-14-31-15 --password ~/MyCertfile.pem --tenant contoso.onmicrosoft.com
+- name: Log in using a VM's system assigned identity.
+  text: az login --identity
+- name: Log in using a VM's user assigned identity. Client or object ids of the service identity also work.
+  text: az login --identity --user /subscriptions/MySubscriptionID/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID
 """
 
 helps['account'] = """
 type: group
-short-summary: Manage Azure subscription information.
+short-summary: Manage Azure subscription information. 
+long-summary: >
+    Use `az login` to log into Azure before managing subscriptions.
+    For an in-depth overview of working with subscriptions using the Azure CLI, see
+    [How to manage Azure subscriptions with the Azure CLI](https://learn.microsoft.com/cli/azure/manage-azure-subscriptions-azure-cli).   
 """
 
 helps['account clear'] = """
 type: command
 short-summary: Clear all subscriptions from the CLI's local cache.
-long-summary: To clear the current subscription, use 'az logout'.
+long-summary: To clear the current subscription, use `az logout`.
 """
 
 helps['account list'] = """
 type: command
-short-summary: >-
-    Get a list of subscriptions for the logged in account. By default, only 'Enabled' subscriptions from the current
-    cloud is shown.
+short-summary: Get a list of subscriptions for the logged in account.
+examples:
+- name: List all subscriptions.
+  text: az account list --all
+- name: List all enabled subscriptions.
+  text: az account list
+- name: Get the current default subscription.
+  text: az account list --query "[?isDefault]"
+- name: Refresh the list of subscriptions. 
+  text: az account list --refresh
 """
 
 helps['account list-locations'] = """
@@ -56,39 +69,69 @@
 helps['account show'] = """
 type: command
 short-summary: Get the details of a subscription.
-long-summary: If no subscription is specified, shows the current subscription.
+long-summary: If no subscription is specified, information for the current subscription is returned.
+examples:
+- name: Get the current default subscription returning results in your default format.
+  text: az account show
+- name: Get information about a named subscription returning results as a table. Use `--output yaml` for plain text.
+  text: az account show --name "My subscription name" --output table
+- name: Get information about a subscription using the subscription ID.
+  text: az account show --name MySubscriptionID
+- name: >
+    Get specific information about a subscription using `--query`.
+    To see available query options, first run `az account show --output json`.
+    For in-depth `--query` examples see [How to query Azure CLI command output using a JMESPath query](https://learn.microsoft.com/cli/azure/query-azure-cli).
+  text: >
+    az account show --query name
+    az account show --query user.name
+- name: Return results in plain text.
+  text: az account show --query MyTenantID --output tsv
+- name: Store the default subscription ID in a variable.
+  text: >
+    # Bash script
+    subscriptionId="$(az account show --query id --output tsv)"
+    echo "The current subscription ID is $subscriptionId"
 """
 
 helps['account set'] = """
 type: command
-short-summary: Set a subscription to be the current active subscription.
-"""
-
-helps['account show'] = """
-type: command
-short-summary: Get the details of a subscription.
-long-summary: If the subscription isn't specified, shows the details of the default subscription.
+short-summary: Change the active subscription.
+examples:
+- name: Change the active subscription using a subscription name
+  text: az account set --subscription "My subscription name"
+- name: Change the active subscription using a subscription ID
+  text: az account set --subscription MySubscriptionID
+- name: Change the active subscription using a variable.
+  text: >
+    # Bash script
+    subscriptionId="$(az account list --query "[?contains(name, 'OneOfMySubscriptionNames')].id" --output tsv)"
+    az account set --subscription $subscriptionId
+    echo "The current subscription has been set to $subscriptionId"
 """
 
 helps['account get-access-token'] = """
 type: command
 short-summary: Get a token for utilities to access Azure.
 long-summary: >
-    The token will be valid for at least 5 minutes with the maximum at 60 minutes.
+    The token will be valid for at least 5 minutes with a maximum of 60 minutes.
     If the subscription argument isn't specified, the current account is used.
 examples:
-    - name: Get an access token for the current account
-      text: >
-        az account get-access-token
-    - name: Get an access token for a specific subscription
-      text: >
-        az account get-access-token --subscription 00000000-0000-0000-0000-000000000000
-    - name: Get an access token for a specific tenant
-      text: >
-        az account get-access-token --tenant 00000000-0000-0000-0000-000000000000
-    - name: Get an access token to use with MS Graph API
-      text: >
-        az account get-access-token --resource-type ms-graph
+- name: Get an access token information for the current account.
+  text: az account get-access-token
+- name: Get an access token information for a specific subscription.
+  text: az account get-access-token --subscription MySubscriptionID
+- name: Get an access token information for a specific tenant.
+  text: az account get-access-token --tenant MySubscriptionID
+- name: Get an access token information to use with MS Graph API.
+  text: az account get-access-token --resource-type ms-graph
+- name: Get an access token information for a particular resource. If you receive a `Failed to connect to MSI...` error, your resource may not exist.
+  text: >
+    az account get-access-token --resource MyResourceID
+    az account get-access-token --resource https://database.windows.net
+- name: Get only the access token for a particular resource returning results in plain text. This script is useful when you want to store the token in a variable.
+  text: az account get-access-token --resource https://management.core.windows.net/ --query accessToken --output tsv
+- name: Get an access token for a particular scope
+  text: az account get-access-token --scope https://management.azure.com//.default
 """
 
 helps['self-test'] = """