(DOCSP-25515): Consolidate CLI output format docs (#806)

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

Author: pierwill

config/redirects

@@ -6,6 +6,8 @@ raw: ${prefix}/ -> ${base}/stable/
 raw: ${prefix} -> ${base}/stable/
 
 #For v1.17 and later, after migration to autogenerated reference docs
+[v1.17-*]: ${prefix}/${version}/reference/json-path/ -> ${base}/${version}/configure/custom-output/
+[v1.17-*]: ${prefix}/${version}/configure/go-template-output/ -> ${base}/${version}/configure/custom-output/
 [v1.17-*]: ${prefix}/${version}/reference/atlas -> ${base}/${version}/command/mongocli-atlas/
 [v1.17-*]: ${prefix}/${version}/reference/atlas/alert-commands -> ${base}/${version}/command/mongocli-atlas-alerts/
 [v1.17-*]: ${prefix}/${version}/reference/atlas/alerts-ack -> ${base}/${version}/command/mongocli-atlas-alerts-acknowledge/

source/configure.txt

@@ -18,7 +18,7 @@ Configure the {+mcli+}
    /configure/configuration-file
    /configure/environment-variables
    /configure/autocomplete
-   /configure/go-template-output
+   /configure/custom-output
 
 You can define the settings that the {+mcli+} uses to interact with
 MongoDB services like |service|, |cloud-short|, and |onprem| by using

source/configure/custom-output.txt

@@ -0,0 +1,252 @@
+.. _go-template-output: 
+
+=============================
+Customize the {+mcli+} Output
+=============================
+
+.. default-domain:: mongodb
+
+You can customize the {+mcli+} output fields and format using a ``Go`` 
+template or a JSON path.
+                    
+Go templates
+------------
+                    
+You can specify the Go template with the command for a simple output 
+or through a separate file for a complex output. For information on the 
+template, see `Package template <https://golang.org/pkg/text/template/>`__. 
+For information on the types and properties available for each response, see: 
+
+- `Atlas types <https://go.mongodb.org/atlas/mongodbatlas/>`__
+- `Cloud Manager types <https://go.mongodb.org/ops-manager/opsmngr/>`__
+- `Ops Manager types <https://go.mongodb.org/ops-manager/opsmngr/>`__
+
+Syntax
+~~~~~~
+
+You can specify a template with the command using the ``--output`` or 
+``-o`` option: 
+
+.. code-block:: shell 
+   :copyable: false 
+
+   --output|-o go-template="{{<template>}}"
+
+You can specify a template using a file using the ``--output`` or 
+``-o`` option: 
+
+.. code-block:: shell 
+   :copyable: false 
+
+   --output|-o go-template-file="<path-to-template-file>"
+
+Examples 
+~~~~~~~~
+
+.. tabs:: 
+
+   .. tab:: Specify Template With the Command
+      :tabid: template-command
+
+      Retrieve the Number of Projects
+      ```````````````````````````````
+
+      The following command uses the template to retrieve a count of 
+      the number of projects in the specified organization using the 
+      {+default-profile+}:
+
+      .. code-block:: shell 
+       
+         mongocli iam projects ls --orgId 5ab5cedf5g5h5i5j5kl12mn4 -o go-template="Count: {{.TotalCount}}"
+
+      The preceding command returns the following output: 
+
+      .. code-block:: shell 
+         :copyable: false 
+
+         Count: 2
+
+      .. _quick-start-atlas-retrieve-conection-string:
+
+      Retrieve Your |service| Cluster Connection String
+      `````````````````````````````````````````````````
+      
+
+      The following :ref:`mongocli-atlas-clusters-describe` command 
+      uses the template to retrieve the connection string for an 
+      |service| cluster named ``getStarted``. It uses the default 
+      profile for accessing |service|. 
+
+      .. code-block:: sh 
+
+         mongocli atlas clusters describe getStarted -o go-template="Parse: {{.SrvAddress}}"
+
+      The previous command returns a string similar to the following: 
+
+      .. code-block:: sh 
+         :copyable: false 
+
+         Parse: mongodb+srv://getstarted.example.mongodb.net
+
+      You can use the MongoDB Shell, {+mongosh+}, to connect to the 
+      ``getStarted`` 
+      cluster with the ``srvAddress`` and the :manual:`connection 
+      string  
+      </reference/connection-string/#connection-string-options>`. This 
+      example uses the following to connect to the |service| cluster: 
+      
+      - The connection string returned by the previous command 
+      - The username and password created in this :ref:`tutorial 
+        <mcli-quick-start-atlas>` 
+
+      .. code-block:: 
+
+         mongo "mongodb+srv://getstarted.example.mongodb.net" --username User1 --password ChangeThisPasswordToSomethingSecure  
+   
+   .. tab:: Specify Template Using a File
+      :tabid: template-file
+
+      For example, consider the following file named ``template.tmpl``: 
+
+      .. code-block:: shell 
+
+         Projects: {{range .Results}}{{.ID}} {{end}}
+      
+      The following command uses the ``template.tmpl`` file to retrieve 
+      the IDs of the projects in the specified organization using the 
+      {+default-profile+}:
+
+      .. code-block:: shell 
+       
+         mongocli iam projects ls --orgId 5ab5cedf5g5h5i5j5kl12mn4 -o go-template-file="template.tmpl"
+
+      The preceding command returns the following output: 
+
+      .. code-block:: shell 
+         :copyable: false 
+
+         Projects: 5e2211c17a3e5a48f5497de3 5f455b39749bea5fb575dccc
+
+.. _json-path-output-option:
+
+``json-path`` Output Type
+-------------------------
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+The ``json-path`` output type limits the results of a command to the 
+fields you specify.
+
+Usage
+~~~~~
+
+When you add the ``--output`` option to a command, you can specify the 
+type ``json-path``. You must provide ``json-path`` with an expression 
+to evaluate against your results, which means you must be aware of the 
+``json`` fields returned by your command.
+
+Syntax
+~~~~~~
+
+.. code-block:: shell
+   :copyable: false
+
+   <command> --output|-o json-path='$<expression>'
+
+``json-path`` expressions refer to the |json| element that a {+mcli+} 
+command returns. The ``$`` character represents the root element, which 
+is usually an object or an array.
+
+For a list of valid characters and their functions, see `JSONPath expressions <https://goessner.net/articles/JsonPath/index.html#e2>`__.
+
+Examples
+~~~~~~~~
+
+Return the description of the first |api| key in a list
+```````````````````````````````````````````````````````
+
+In the following example, a user retrieves their |api| keys with 
+:ref:`mongocli-iam-organizations-apiKeys-list`. The ``json-path`` 
+expression limits the output to the ``desc`` field of the first key, 
+rather than returning the entire list of keys.
+
+.. code-block:: shell
+   :copyable: false 
+
+   mongocli iam organization apikeys list --output json-path='$[0].desc'
+   > owner_key
+
+Running the same command with ``--output json`` returns the full |json| 
+element from the |api|. It's important to understand the |json| 
+structure returned by a command in order to operate on it with 
+``json-path``.
+
+Using the the following full |json| output for reference, the 
+``--output json-path`` with the expression ``$[0].desc`` finds and 
+returns only the value ``"owner_key"``:
+
+.. code-block:: json
+   :copyable: false
+   :emphasize-lines: 1-2, 4
+
+   [ //``$`` represents the outer array.
+     { // ``[0]`` refers to the first element in the array (using a 0-based index).
+       "id": "60e736a95d585d2c9ccf2d19",
+       "desc": "owner_key", //``.desc`` refers to the ``desc`` field of that element.
+       "roles": [
+         {
+           "orgId": "5d961a949ccf64b4e7f53bac",
+           "roleName": "ORG_OWNER"
+         }
+       ],
+       "privateKey": "********-****-****-c4e26334754f",
+       "publicKey": "xtfmtguk"
+     },
+     {
+       "id": "d2c9ccf2d1960e736a95d585",
+       "desc": "member_key",
+       "roles": [
+         {
+           "orgId": "5d961a949ccf64b4e7f53bac",
+           "roleName": "ORG_MEMBER"
+         }
+       ],
+       "privateKey": "********-****-****-c4e26334754f",
+       "publicKey": "vfgcttku"
+     },
+   ]
+
+Return the description of a specific |api| key in a list
+````````````````````````````````````````````````````````
+
+In the following example, a user retrieves their |api| keys with 
+:ref:`mongocli-iam-organizations-apiKeys-list`. The ``json-path`` 
+expression limits the output to the ``desc`` field of the specific 
+|json| object with ``id`` ``d2c9ccf2d1960e736a95d585``.
+
+.. code-block:: shell
+   :copyable: false 
+   
+   mongocli iam organization apikeys list --output json-path='$[? @.id=="d2c9ccf2d1960e736a95d585"].desc'
+   > member_key
+
+Return the status of a private endpoint
+```````````````````````````````````````
+
+In the following example, a user retrieves information for a 
+private endpoint with 
+:ref:`mongocli-atlas-privateEndpoints-aws-describe`. The ``json-path`` 
+expression limits the output to the ``status`` field of the root 
+element.
+
+.. code-block:: shell
+   :copyable: false 
+
+   mongocli atlas privateendpoint aws describe 601a4044da900269480a2533 --output json-path='$.status'
+   > WAITING_FOR_USER