Hasura CLI Configuration Reference

Introduction

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

Note

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

For the Hasura CLI to work, the config.yaml file is required and created automatically when running the hasura init command. You can configure the configuration file with the following config keys:

version:
endpoint:
admin_secret:
admin_secrets:
insecure_skip_tls_verify:
certificate_authority:
access_key: #deprecated
api_paths:
  query:
  graphql:
  config:
  pg_dump:
  version:
metadata_directory:
migrations_directory:
seeds_directory:
actions:
  kind:
  handler_webhook_baseurl:
  codegen:
    framework:
    output_dir:
    uri:

Config Key	Required	Supported since Config Version	Default value
version	false	1	3
endpoint	true	1	http://localhost:8080
admin_secret	false	1
admin_secrets	false	3 (added in v2.8.0)
access_key	false	1 (Deprecated)
insecure_skip_tls_verify	false	1 (added in v1.2.0)	false
certificate_authority	false	1 (added in v1.2.0)
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
seeds_directory	false	2
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

Note

The above structure is for the config v3 file which is supported since v2.0.0-alpha.1. Refer to this page on how to upgrade to config v2.

A .env file

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.

It's important to note that this will not override an environment variable that already exists.

As an example, the command below will read environment variables from the production.env file present at the project's root directory.

hasura console --envfile production.env

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 for Hasura GraphQL Engine (Cloud/Enterprise Edition 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).
HASURA_GRAPHQL_API_PATHS_GRAPHQL	api_paths.graphql	GraphQL API endpoint. More details at GraphQL API.
HASURA_GRAPHQL_API_PATHS_CONFIG	api_paths.config	Config API endpoint. More details at Config API`.
HASURA_GRAPHQL_API_PATHS_PG_DUMP	api_paths.pg_dump	PG Dump API endpoint. More details at pg_dump API.
HASURA_GRAPHQL_API_PATHS_VERSION	api_paths.version	Version API endpoint. More details at RESTified GraphQL 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:

hasura metadata apply --endpoint "https://my-project.hasura.app"

Custom request headers

The --header flag lets you attach arbitrary HTTP headers to every request the CLI makes to the Hasura GraphQL Engine (or to a gateway in front of it). This is useful when the engine or gateway authenticates requests with something other than an admin secret — for example a JWT in an Authorization header.

The flag is available on the CLI commands that communicate with the engine, including hasura migrate ..., hasura metadata ..., hasura seed ..., hasura deploy, hasura actions ... and hasura console. It takes a value in Name: value form and can be repeated to send multiple headers:

hasura metadata export --header "Authorization: Bearer <JWT>"

hasura migrate apply \
  --header "Authorization: Bearer <JWT>" \
  --header "X-Tenant-Id: acme"

Notes and semantics:

• Repeatable: specify --header once per header you want to send.
• Values are preserved verbatim: only the first : separates the name from the value, so values may themselves contain : and , (for example Bearer tokens or URLs). Only optional spaces and horizontal tabs around the value are trimmed.
• Validation: header names must be valid HTTP tokens and neither names nor values may contain carriage-return, line-feed or other control characters (a trailing \r\n is rejected rather than silently stripped). Malformed input is rejected with an error that never prints the header value, so secrets are not leaked to the terminal, logs or telemetry.
• Duplicates: specifying the same header name more than once (compared case-insensitively) is rejected, so the request sent to the server is unambiguous.
• Precedence with the admin secret: if an admin secret is configured (via --admin-secret, the config file or an environment variable) it continues to be sent as before. A --header value takes precedence only when it targets the same header name (for example X-Hasura-Admin-Secret); header names are compared case-insensitively, so exactly one value is sent for that header and the --header value wins. Headers with other names are sent in addition to the admin secret header.
• No admin secret configured: when no admin secret is set, the CLI does not send an X-Hasura-Admin-Secret (or legacy X-Hasura-Access-Key) header at all. This lets a custom auth header such as --header "x-api-key: ..." or --header "Authorization: Bearer ..." be honoured by the server's auth webhook/JWT — previously an empty admin-secret header was sent, which a server with an admin secret would reject before consulting the webhook. Custom headers are applied to every request the CLI makes to the engine, including the /v1/version probe.
• Not persisted: --header is a command-line flag only. Its values are never written to config.yaml and are not read from environment variables or the config file, which keeps credentials such as JWTs out of your project configuration.

Authorization is enforced by the server

These flags only transport headers; they do not grant any privileges by themselves. The destination engine or gateway must be configured to authorize the requested migrate/metadata operation for the identity the header represents. An ordinary JWT does not, on its own, confer the metadata/admin privileges that these operations usually require. Conversely, if an admin secret is configured it may still grant admin access — supplying a custom header does not disable it.