docs: add reference docs for cli (fix #4327)

CHANGELOG.md

@@ -18,6 +18,7 @@
 - console: prevent trailing spaces while creating new role (close #3871) (#4497)
 - docs: add API docs for using environment variables as webhook urls in event triggers
 - server: fix recreating action's permissions (close #4377)
+- docs: add reference docs for CLI (clsoe #4327) (#4408)
 
 ## `v1.2.0-beta.4`
 

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

@@ -23,6 +23,10 @@ Installation
 
 Refer to :ref:`install_hasura_cli`.
 
+Configuration
+-------------
+
+Refer to :ref:`cli_reference`.
 
 Commands
 --------
@@ -71,6 +75,7 @@ Refer to :ref:`uninstall_hasura_cli`.
    :hidden:
 
    install-hasura-cli
+   reference
    hasura <hasura>
    hasura actions <hasura_actions>
    hasura actions codegen <hasura_actions_codegen>

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

@@ -0,0 +1,236 @@
+.. meta::
+   :description: Haura GarphQL CLI configuration reference 
+   :keywords: hasura, docs, CLI, CLI reference, config 
+
+.. _cli_reference:
+
+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
+^^^^^^^^^^^^^^^^^^
+
+In order for the Hasura CLI to work, the ``config.yaml`` file is required (created automatically via the :ref:`hasura init<hasura_init>` command).
+The configuration file can be configured with the following config keys:
+
+.. 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
+^^^^^^^^^^^^^^^^^^^^^
+
+The configuration can also be set in the form of 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.
+
+CLI flags
+^^^^^^^^^
+
+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. 
+
+.env file
+^^^^^^^^^
+
+Alternatively, environment variables can also be read from the ``.env`` file, created manually 
+by the user, at the project root directory. A global flag, ``--envfile``, is available to 
+explicitly get the ``.env`` file created by the user, which defaults to ``.env`` if 
+no flag is provided. 
+
+It's important to note that this will not override an ENV variable that already exists.
+
+Example:
+
+::
+
+  hasura console --envfile production.env
+
+The above command will read ENV vars from the ``production.env`` file present at the 
+project root directory. 
+
+.. note::
+
+  Precedence order is flag > ENV vars > ``.env`` file values > configuration file values > default.