docs: add reference docs for hasura CLI

This commit adds docs for CLI configuration file and ENV
vars.

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Bug fixes and improvements
 
+- docs: add reference docs for CLI (clsoe #4327) (#4408)
 - server: add support for `_inc` on `real`, `double`, `numeric` and `money` (fix #3573)
 - server: support special characters in JSON path query argument with bracket `[]` notation, e.g `obj['Hello World!']` (#3890) (#4482)
 - server: add graphql-engine support for timestamps without timezones (fix #1217)

docs/graphql/manual/hasura-cli/index.rst

@@ -104,3 +104,4 @@ Refer to :ref:`uninstall_hasura_cli`.
    hasura update-cli <hasura_update-cli>
    hasura version <hasura_version>
    uninstall-hasura-cli
+   reference

docs/graphql/manual/hasura-cli/reference.rst

@@ -0,0 +1,213 @@
+.. meta::
+   :description: Haura GarphQL CLI configuration reference 
+   :keywords: hasura, docs, CLI, CLI reference, config 
+
+.. _cli_reference:
+
+Hasura CLI configuration reference 
+==================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Hasura CLI commands get key values from flags, ENV variables, ``.env`` file and configuration file ``config.yaml``. 
+
+Configuration file
+^^^^^^^^^^^^^^^^^^
+
+The configuration file, ``config.yaml`` format:
+
+.. code-block:: none
+
+  version: 
+  endpoint: 
+  admin_secret:
+  access_key: #deprecated
+  api_paths:
+    query: 
+    graphql: 
+    config: 
+    pg_dump: 
+    version: 
+  metadata_directory:
+  migrations_directory: 
+  actions:
+    kind: 
+    handler_webhook_baseurl: 
+    codegen:
+      framework:
+      output_dir:
+      uri:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Config Key
+     - Required
+     - Supported since Config Version
+     - Default value
+   * - version
+     - false
+     - 1
+     - 2
+   * - endpoint
+     - true
+     - 1
+     - http://localhost:8080
+   * - admin_secret
+     - false
+     - 1
+     -
+   * - access_key
+     - false
+     - 1 (Deprecated)
+     - 
+   * - api_paths
+     - false
+     - 1
+     -
+   * - api_paths.query
+     - false
+     - 1
+     - v1/query 
+   * - api_paths.graphql
+     - false
+     - 1
+     - v1/graphql
+   * - api_paths.config
+     - false
+     - 1
+     - v1alpha1/config
+   * - api_paths.pg_dump
+     - false
+     - 1
+     - v1alpha1/pg_dump
+   * - api_paths.version
+     - false
+     - 1
+     - v1/version
+   * - metadata_directory
+     - false
+     - 2
+     - 
+   * - migrations_directory
+     - false
+     - 1
+     - migrations
+   * - actions
+     - false
+     - 2
+     -
+   * - actions.kind
+     - true 
+     - 2
+     - synchronous
+   * - actions.handler_webhook_baseurl
+     - true
+     - 2
+     - http://localhost:3000
+   * - actions.codegen
+     - false
+     - 2
+     -   
+   * - actions.codegen.framework
+     - true
+     - 2
+     -
+   * - actions.codegen.output_dir
+     - true 
+     - 2
+     -
+   * - actions.codegen.uri
+     - false
+     - 2
+     -
+
+
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 30
+
+   * - ENV variable
+     - Configuration file key
+     - Description
+
+   * - ``HASURA_GRAPHQL_VERSION``
+     - ``version``
+     - Config version to be used. 
+
+   * - ``HASURA_GRAPHQL_ENDPOINT``
+     - ``endpoint``
+     - http(s) endpoint for Hasura GraphQL Engine.
+
+   * - ``HASURA_GRAPHQL_ADMIN_SECRET``
+     - ``admin_secret``  
+     - Admin secret for Hasura GraphQL Engine. 
+
+   * - ``HASURA_GRAPHQL_ACCESS_KEY``
+     - ``access_key``
+     - Access key for Hasura GraphQL Engine. Note: Deprecated. Use admin 
+       secret instead. 
+
+   * - ``HASURA_GRAPHQL_API_PATHS_QUERY``
+     - ``api_paths.query``
+     - Schema/ metadata API endpoint. More details at :ref:`schema_metadata_api`.
+
+   * - ``HASURA_GRAPHQL_API_PATHS_GRAPHQL``
+     - ``api_paths.graphql``
+     - GraphQL API endpoint. More details at :ref:`graphql_api`.
+
+   * - ``HASURA_GRAPHQL_API_PATHS_CONFIG``
+     - ``api_paths.config``
+     - Config API endpoint. More details at :ref:`config_api`.
+
+   * - ``HASURA_GRAPHQL_API_PATHS_PG_DUMP``
+     - ``api_paths.pg_dump``
+     - PG Dump API endpoint. More details at :ref:`pg_dump_api`.
+
+   * - ``HASURA_GRAPHQL_API_PATHS_VERSION``
+     - ``api_paths.version``
+     - Version API endpoint. More details at :ref:`version_api`.
+
+   * - ``HASURA_GRAPHQL_METADATA_DIRECTORY``
+     - ``metadata_directory``
+     - Defines the directory where the metadata files were stored.
+
+   * - ``HASURA_GRAPHQL_MIGRATIONS_DIRECTORY``
+     - ``migrations_directory``
+     - Defines the directory where the migration files were stored.
+
+   * - ``HASURA_GRAPHQL_ACTIONS_KIND``
+     - ``actions.kind``
+     - Kind to be used for actions.
+
+   * - ``HASURA_GRAPHQL_ACTIONS_HANDLER_WEBHOOK_BASEURL``
+     - ``actions.handler_webhook_baseurl``
+     - Webhook baseurl to be used for actions. 
+
+   * - ``HASURA_GRAPHQL_ACTIONS_CODEGEN_FRAMEWORK``
+     - ``actions.codegen.framework``
+     - Framework to codegen for actions.
+
+   * - ``HASURA_GRAPHQL_ACTION_CODEGEN_OUTPUT_DIR``
+     - ``actions.codegen.output_dir``
+     - Defines the directory to create the codegen files.
+
+   * - ``HASURA_GRAPHQL_ACTION_CODEGEN_URI``
+     - ``actions.codegen.uri``
+     - URI to codegen for actions.
+
+The above keys can be set using command-line flags as well. The corresponding flag, 
+for the ENV vars or the configuration keys, can be found in the respective commands 
+reference manual. 
+
+The ENV vars can be declared in the ``.env`` file as well. It's important to note 
+that it will not override an ENV variable that already exists.
+
+.. note::
+
+  Precedence order is Flag > ENV vars > ``.env`` file values > Configuration file values > default