docs: restructure cli section

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6971
Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com>
GitOrigin-RevId: 161396ef07386d6032232bb3e9926b7520f1b5ba
This commit is contained in:
Rob Dominguez 2022-11-29 17:37:54 -06:00 committed by hasura-bot
parent 698190894f
commit 29e3a0eb1b
6 changed files with 169 additions and 180 deletions

View File

@ -1,4 +1,4 @@
{
"label": "Commands",
"position": 3
"position": 2
}

View File

@ -17,7 +17,7 @@ The Hasura CLI utilizes a typical command / flag syntax enabling you to quickly
command structure will follow this pattern:
```bash
hasura <command_category> <specific_command> --<optional_flag> "<optional_flag_value>"
hasura <command> <subcommand> --<optional_flag> "<optional_flag_value>"
```
A real-world example following this structure would be:
@ -26,9 +26,12 @@ A real-world example following this structure would be:
hasura migrate apply --admin-secret "<admin-secret>"
```
This snippet illustrates the `migrate` command used in conjunction with the `apply` subcommand, the `admin-secret` flag,
and the value of the `admin-secret`.
## Getting help
At any time, you may use the `--help` flag on either the CLI itself or specific to a certain command. Writing
At any time, you can use the `--help` flag on either the CLI itself or specific to a certain command. Running
`hasura --help` will return information on available commands and flags:
```
@ -69,7 +72,7 @@ Flags:
Use "hasura [command] --help" for more information about a command.
```
Whereas writing `hasura actions --help` will return commands and flags specific to the `actions` category of commands:
Whereas running `hasura actions --help` will return commands and flags specific to the `actions` category of commands:
```
Manage Hasura actions
@ -99,5 +102,9 @@ Global Flags:
Use "hasura actions [command] --help" for more information about a command.
```
:::info Note
A complete list of all CLI commands, including details and examples, can be found in the side navigation to the left
under the Commands heading.
:::

View File

@ -1,6 +1,6 @@
---
sidebar_label: Configuration Reference
sidebar_position: 2
sidebar_position: 3
description: Hasura GraphQL CLI configuration reference
keywords:
- hasura
@ -14,19 +14,27 @@ keywords:
## Introduction
Hasura CLI commands can get key values from flags, ENV variables, a
`.env` file or the configuration file `config.yaml`.
When using the Hasura CLI, you'll pass various values to different commands. These values can be configured using:
- a configuration file
- a `.env` file
- environment variables
- flags to the command itself
:::info Note
Precedence order is flag > ENV vars > `.env` file values >
configuration file values > default.
The order of precedence by which the CLI processes these values is flag -> environment variables -> `.env` file
values -> configuration file values -> default.
In the sections below, we'll explain how to configure the CLI for each of these use cases.
:::
## Configuration file
In order for the Hasura CLI to work, the `config.yaml` file is required (created automatically via the [hasura init](/hasura-cli/commands/hasura_init.mdx) command). The configuration file can be configured with the following config keys:
For the Hasura CLI to work, the `config.yaml` file is required and created automatically when running the
[hasura init](/hasura-cli/commands/hasura_init.mdx) command. You can configure the configuration file with the following
config keys:
```yaml
version:
@ -82,62 +90,67 @@ actions:
:::info Note
The above structure is for the `config v3` file which is supported since `v2.0.0-alpha.1`. Refer to [this page](/migrations-metadata-seeds/legacy-configs/upgrade-v3.mdx) on how to upgrade to `config v2`.
The above structure is for the `config v3` file which is supported since `v2.0.0-alpha.1`. Refer to
[this page](/migrations-metadata-seeds/legacy-configs/upgrade-v3.mdx) on how to upgrade to `config v2`.
:::
## Environment variables
## A `.env` file
The configuration can also be set in the form of environment variables:
Alternatively, the Hasura CLI can also read environment variables from a `.env` file, created manually by the user, at
the project's root directory. A global flag, `--envfile`, is available to explicitly identify the `.env` file which
defaults to `.env` if you don't provide it.
| ENV variable | Config 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_ADMIN_SECRETS` | `admin_secrets` | [Admin secrets](/security/multiple-admin-secrets.mdx) for Hasura GraphQL engine _(Cloud/EE only)_. eg: `HASURA_GRAPHQL_ADMIN_SECRETS='["foo", "bar", "baz"]'` |
| `HASURA_GRAPHQL_ACCESS_KEY` | `access_key` | Access key for Hasura GraphQL engine. Note: Deprecated. Use admin secret instead. |
| `HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY` | `insecure_skip_tls_verify` | Skip verifying SSL certificate for the Hasura endpoint. Useful if you have a self-singed certificate and don't have access to the CA cert. |
| `HASURA_GRAPHQL_CERTIFICATE_AUTHORITY` | `certificate_authority` | Path to the CA certificate for validating the self-signed certificate for the Hasura endpoint. |
| `HASURA_GRAPHQL_API_PATHS_QUERY` | `api_paths.query` | Schema/ metadata API endpoint. More details at [Schema / metadata API (Deprecated)](/api-reference/index.mdx#schema-metadata-api). |
| `HASURA_GRAPHQL_API_PATHS_GRAPHQL` | `api_paths.graphql` | GraphQL API endpoint. More details at [GraphQL API](/api-reference/index.mdx#graphql-api). |
| `HASURA_GRAPHQL_API_PATHS_CONFIG` | `api_paths.config` | Config API endpoint. More details at [Config API](/api-reference/index.mdx#config-api)`. |
| `HASURA_GRAPHQL_API_PATHS_PG_DUMP` | `api_paths.pg_dump` | PG Dump API endpoint. More details at [pg_dump API](/api-reference/index.mdx#pg-dump-api). |
| `HASURA_GRAPHQL_API_PATHS_VERSION` | `api_paths.version` | Version API endpoint. More details at [RESTified GraphQL API](/api-reference/index.mdx#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_SEEDS_DIRECTORY` | `seeds_directory` | Defines the directory where the seed 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. |
It's important to note that this will not override an environment variable that already exists.
## CLI flags
As an example, the command below will read environment variables from the `production.env` file present at the
project's root directory.
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.
```bash
hasura console --envfile production.env
```
:::tip Supported from
`.env` file is supported in versions `v1.2.0` and above.
:::
## Environment variables
The following environment variables can be utilized to configure different values on a per-project basis for use with
the CLI:
| Environment variable | Config 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_ADMIN_SECRETS` | `admin_secrets` | [Admin secrets](/security/multiple-admin-secrets.mdx) for Hasura GraphQL engine _(Cloud/EE only)_. eg: `HASURA_GRAPHQL_ADMIN_SECRETS='["foo", "bar", "baz"]'` |
| `HASURA_GRAPHQL_ACCESS_KEY` | `access_key` | Access key for Hasura GraphQL engine. Note: Deprecated. Use admin secret instead. |
| `HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY` | `insecure_skip_tls_verify` | Skip verifying SSL certificate for the Hasura endpoint. Useful if you have a self-singed certificate and don't have access to the CA cert. |
| `HASURA_GRAPHQL_CERTIFICATE_AUTHORITY` | `certificate_authority` | Path to the CA certificate for validating the self-signed certificate for the Hasura endpoint. |
| `HASURA_GRAPHQL_API_PATHS_QUERY` | `api_paths.query` | Schema/ metadata API endpoint. More details at [Schema / metadata API (Deprecated)](/api-reference/index.mdx#schema-metadata-api). |
| `HASURA_GRAPHQL_API_PATHS_GRAPHQL` | `api_paths.graphql` | GraphQL API endpoint. More details at [GraphQL API](/api-reference/index.mdx#graphql-api). |
| `HASURA_GRAPHQL_API_PATHS_CONFIG` | `api_paths.config` | Config API endpoint. More details at [Config API](/api-reference/index.mdx#config-api)`. |
| `HASURA_GRAPHQL_API_PATHS_PG_DUMP` | `api_paths.pg_dump` | PG Dump API endpoint. More details at [pg_dump API](/api-reference/index.mdx#pg-dump-api). |
| `HASURA_GRAPHQL_API_PATHS_VERSION` | `api_paths.version` | Version API endpoint. More details at [RESTified GraphQL API](/api-reference/index.mdx#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_SEEDS_DIRECTORY` | `seeds_directory` | Defines the directory where the seed 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. |
## Flags
The keys in the previous section can be set using command line flags. The corresponding flag, for the environment
variable or the configuration keys, can be found in the respective commands reference manual.
As an example, the `--endpoint` flag can be used to set the `HASURA_GRAPHQL_ENDPOINT` environment variable:
```bash
hasura metadata apply --endpoint "https://my-project.hasura.app"
```

View File

@ -12,61 +12,38 @@ slug: index
## Introduction
The Hasura CLI is a command line tool which, along with the Hasura Console is one of the primary modes of managing your
Hasura instances.
The Hasura CLI is a command-line tool you can use to manage your Hasura instances.
Most often with Hasura CLI you will be working with Hasura Migrations and Hasura Metadata.
[Check out the documentation on those](/migrations-metadata-seeds/index.mdx) to see how they work.
We offer two primary methods for working with your Hasura instances: the Hasura Console and the Hasura CLI. While the
Console is robust and provides an easy-to-navigate GUI for interacting with your project, the CLI offers a more powerful
interface for managing your project.
The CLI is useful for:
- [managing Metadata](/migrations-metadata-seeds/manage-metadata.mdx).
- [creating and applying Migrations](/migrations-metadata-seeds/manage-migrations.mdx).
- integrating with your CI/CD pipeline.
- automating tasks.
You can use the CLI to initialize a new Hasura project from the very beginning, or you can use it to manage an
existing one.
## Installation
Refer to [Installing the Hasura CLI](/hasura-cli/install-hasura-cli.mdx).
Installation is quick and easy with npm:
## Configuration
```bash
npm install -g hasura-cli
```
Refer to [Hasura CLI Configuration Reference](/hasura-cli/config-reference.mdx).
Or, if you prefer to install the binaries, check out our [installation guide](/hasura-cli/install-hasura-cli.mdx).
## Commands
## Usage
- [hasura actions](/hasura-cli/commands/hasura_actions.mdx)
- [hasura](/hasura-cli/commands/hasura.mdx)
- [hasura actions codegen](/hasura-cli/commands/hasura_actions_codegen.mdx)
- [hasura actions create](/hasura-cli/commands/hasura_actions_create.mdx)
- [hasura actions use-codegen](/hasura-cli/commands/hasura_actions_use-codegen.mdx)
- [hasura completion](/hasura-cli/commands/hasura_completion.mdx)
- [hasura console](/hasura-cli/commands/hasura_console.mdx)
- [hasura deploy](/hasura-cli/commands/hasura_deploy.mdx)
- [hasura init](/hasura-cli/commands/hasura_init.mdx)
- [hasura metadata](/hasura-cli/commands/hasura_metadata.mdx)
- [hasura metadata apply](/hasura-cli/commands/hasura_metadata_apply.mdx)
- [hasura metadata clear](/hasura-cli/commands/hasura_metadata_clear.mdx)
- [hasura metadata diff](/hasura-cli/commands/hasura_metadata_diff.mdx)
- [hasura metadata export](/hasura-cli/commands/hasura_metadata_export.mdx)
- [hasura metadata inconsistency](/hasura-cli/commands/hasura_metadata_inconsistency.mdx)
- [hasura metadata inconsistency drop](/hasura-cli/commands/hasura_metadata_inconsistency_drop.mdx)
- [hasura metadata inconsistency list](/hasura-cli/commands/hasura_metadata_inconsistency_list.mdx)
- [hasura metadata inconsistency status](/hasura-cli/commands/hasura_metadata_inconsistency_status.mdx)
- [hasura metadata reload](/hasura-cli/commands/hasura_metadata_reload.mdx)
- [hasura migrate](/hasura-cli/commands/hasura_migrate.mdx)
- [hasura migrate apply](/hasura-cli/commands/hasura_migrate_apply.mdx)
- [hasura migrate create](/hasura-cli/commands/hasura_migrate_create.mdx)
- [hasura migrate delete](/hasura-cli/commands/hasura_migrate_delete.mdx)
- [hasura migrate squash](/hasura-cli/commands/hasura_migrate_squash.mdx)
- [hasura migrate status](/hasura-cli/commands/hasura_migrate_status.mdx)
- [hasura plugins](/hasura-cli/commands/hasura_plugins.mdx)
- [hasura plugins install](/hasura-cli/commands/hasura_plugins_install.mdx)
- [hasura plugins list](/hasura-cli/commands/hasura_plugins_list.mdx)
- [hasura plugins uninstall](/hasura-cli/commands/hasura_plugins_uninstall.mdx)
- [hasura plugins upgrade](/hasura-cli/commands/hasura_plugins_upgrade.mdx)
- [hasura scripts](/hasura-cli/commands/hasura_scripts.mdx)
- [hasura scripts update-project-v2](/hasura-cli/commands/hasura_scripts_update-project-v2.mdx)
- [hasura scripts update-project-v3](/hasura-cli/commands/hasura_scripts_update-project-v3.mdx)
- [hasura seed](/hasura-cli/commands/hasura_seed.mdx)
- [hasura seed apply](/hasura-cli/commands/hasura_seed_apply.mdx)
- [hasura seed create](/hasura-cli/commands/hasura_seed_create.mdx)
- [hasura update-cli](/hasura-cli/commands/hasura_update-cli.mdx)
- [hasura version](/hasura-cli/commands/hasura_version.mdx)
The CLI has a number of commands you can use to manage your project. You can see the full list of commands by running:
`hasura --help`.
## Uninstalling
There are many subcommands too; you can see the available subcommands and their arguments by running a command with the
`--help` flag, for example: `hasura metadata --help`.
Refer to [Uninstalling the Hasura CLI](/hasura-cli/uninstall-hasura-cli.mdx).
After installing, we suggest getting started by heading to the [CLI commands reference](/hasura-cli/commands/index.mdx).

View File

@ -1,5 +1,5 @@
---
sidebar_label: Installing the Hasura CLI
sidebar_label: Installing / Uninstalling
sidebar_position: 1
description: Install the Hasura CLI on Linux, Mac OS, Windows
keywords:
@ -11,13 +11,33 @@ keywords:
- windows
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Link from '@docusaurus/Link';
# Installing the Hasura CLI
# Installing / Uninstalling the Hasura CLI
## Install a binary globally
## Installing the Hasura CLI
### Installing through npm
The Hasura CLI is conveniently available as an npm package which wraps the compiled binary and is independently
maintained by members of the community. It can be beneficial to use the npm package if you want a version-fixed CLI
dedicated to your node.js project. You can find usage details (e.g. flag information) in the
[original repository](https://github.com/jjangga0214/hasura-cli). To install the CLI, you can use npm (or yarn):
```bash
# install as a devDependency of your project
npm install --save-dev hasura-cli[@tag|@version]
# or install globally on your system
npm install --global hasura-cli[@tag|@version]
```
### Installing the Hasura CLI binary globally
If you prefer to install the binary globally, you can download it by following the instructions for your
operating system:
<Tabs className="api-tabs">
<TabItem value="linux" label="Linux">
@ -28,19 +48,17 @@ In your Linux shell, run the following command:
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash
```
This will install the Hasura CLI in `/usr/local/bin`. You might have to
provide your `sudo` password depending on the permissions of your
`/usr/local/bin` location.
This will install the Hasura CLI in `/usr/local/bin`. You might have to provide your `sudo` password depending on the
permissions of your `/usr/local/bin` location.
If you'd prefer to install to a different location other than
`/usr/local/bin`, set the `INSTALL_PATH` variable accordingly:
If you'd prefer to install to a different location other than `/usr/local/bin`, set the `INSTALL_PATH` variable
accordingly:
```bash
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | INSTALL_PATH=$HOME/bin bash
```
You can also install a specific version of the CLI by providing the
`VERSION` variable:
You can also install a specific version of the CLI by providing the `VERSION` variable:
```bash
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | VERSION=v2.2.0 bash
@ -55,19 +73,17 @@ In your Terminal, run the following command:
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash
```
This will install the Hasura CLI in `/usr/local/bin`. You might have to
provide your `sudo` password depending on the permissions of your
`/usr/local/bin` location.
This will install the Hasura CLI in `/usr/local/bin`. You might have to provide your `sudo` password depending on the
permissions of your `/usr/local/bin` location.
If you'd prefer to install to a different location other than
`/usr/local/bin`, set the `INSTALL_PATH` variable accordingly:
If you'd prefer to install to a different location other than `/usr/local/bin`, set the `INSTALL_PATH` variable
accordingly:
```bash
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | INSTALL_PATH=$HOME/bin bash
```
You can also install a specific version of the CLI by providing the
`VERSION` variable:
You can also install a specific version of the CLI by providing the `VERSION` variable:
```bash
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | VERSION=v2.2.0 bash
@ -76,31 +92,47 @@ curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | VERSION
</TabItem>
<TabItem value="windows" label="Windows">
Download the binary `cli-hasura-windows-amd64.exe` available under
`Assets` of the latest release from the GitHub release page : <Link to="https://github.com/hasura/graphql-engine/releases">https://github.com/hasura/graphql-engine/releases</Link>
Download the binary `cli-hasura-windows-amd64.exe` available under `Assets` of the latest release from the GitHub
release page :
Rename the downloaded file to `hasura`. You can add the path to the
environment variable `PATH` for making `hasura` accessible globally.
<Link to='https://github.com/hasura/graphql-engine/releases'>https://github.com/hasura/graphql-engine/releases</Link>
Rename the downloaded file to `hasura`. You can add the path to the environment variable `PATH` for making `hasura`
accessible globally.
</TabItem>
</Tabs>
## Install through npm
:::tip Tip: Add shell completion
Hasura CLI is available as an npm package that is independently
maintained by some members of the community. It can be beneficial to use
the npm package if you want a version-fixed cli dedicated to your
node.js project. You can find usage details (e.g. flag information) in
the [original repository](https://github.com/jjangga0214/hasura-cli).
To add command auto-completion in your shell, refer to the
[hasura completion](/hasura-cli/commands/hasura_completion.mdx) command.
:::
## Uninstalling the Hasura CLI
### Uninstalling through npm
If you installed the CLI as an npm package, use npm (or yarn):
```bash
# install as a devDependency of your project
npm install --save-dev hasura-cli[@tag|@version]
# if installed as a project dependency
npm uninstall hasura-cli
# or install globally on your system
npm install --global hasura-cli[@tag|@version]
# if installed as a global package
npm uninstall --global hasura-cli
```
## (Optional) Add shell completion
### Uninstalling a binary globally
To add command auto completion in the shell, refer to [hasura completion](/hasura-cli/commands/hasura_completion.mdx).
If you installed the binary directly on your system, delete the binary file from its installation location.
```bash
# By default, the binary is installed at /usr/local/bin/hasura
$ which hasura
/usr/local/bin/hasura
# use sudo if required
$ rm /usr/local/bin/hasura
```

View File

@ -1,40 +0,0 @@
---
sidebar_label: Uninstalling the Hasura CLI
sidebar_position: 5
description: Uninstall the Hasura CLI on Linux, Mac OS, Windows
keywords:
- hasura
- hasura CLI
- uninstall
- linux
- mac
- windows
---
# Uninstalling the Hasura CLI
## Uninstall a binary
If you installed the binary directly on your system (probably through
shell script), delete the binary file from its installation location.
```bash
# By default, the binary is installed at /usr/local/bin/hasura
$ which hasura
/usr/local/bin/hasura
# use sudo if required
$ rm /usr/local/bin/hasura
```
## Uninstall an npm package
If you installed the CLI as an npm package, use npm (or yarn).
```bash
# if installed as a project dependency
npm uninstall hasura-cli
# if installed as a global package
npm uninstall --global hasura-cli
```