cli

README

Hasura GraphQL Engine CLI

Installation

Download GraphQL Engine CLI bundled with Hasura CLI

• Linux/macOS

  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.

  If you’d prefer to install to a different location other than /usr/local/bin, set the INSTALL_PATH variable accordingly:

  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:

  curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | VERSION=v2.28.0 bash
  

• Windows

  Download the binary cli-hasura-windows-amd64.exe available under Assets of the latest release from the GitHub release page: https://github.com/hasura/graphql-engine/releases

Download using go get

go get github.com/hasura/graphql-engine/cli/cmd/hasura

Build from source

git clone https://github.com/hasura/graphql-engine
cd graphql-engine/cli
make deps
make build-cli-ext copy-cli-ext
make build
# binaries will be in _output directory

Usage

hasura init --directory <my-project> --endpoint <graphql-endpoint> --admin-secret <admin-secret>
cd <my-project>
hasura console

Contributing

Checkout the contributing guide.

Documentation

Overview

Package cli and it's sub packages implements the command line tool for Hasura GraphQL Engine. The CLI operates on a directory, denoted by "ExecutionDirectory" in the "ExecutionContext" struct.

The ExecutionContext is passed to all the subcommands so that a singleton context is available for the execution. Logger and Spinner comes from the same context.

Index

• Constants
• Variables
• func CheckFilesystemBoundary(dir string) error
• func GetAdminSecretHeaderName(v *version.Version) string
• func GetCommonMetadataOps(ec *ExecutionContext) hasura.CommonMetadataOperations
• func GetMigrationsStateStore(ec *ExecutionContext) statestore.MigrationsStateStore
• func GetSettingsStateStore(ec *ExecutionContext, databaseName string) statestore.SettingsStateStore
• func ValidateDirectory(dir string) error
• type Config
• type ConfigVersion
  • func NewConfigVersionValue(val ConfigVersion, p *ConfigVersion) *ConfigVersion
  • func (c ConfigVersion) IsValid() bool
  • func (c *ConfigVersion) Set(s string) error
  • func (c *ConfigVersion) String() string
  • func (c *ConfigVersion) Type() string
• type DefaultAPIPath
• type Environment
• type ExecutionContext
  • func NewExecutionContext() *ExecutionContext
  • func (ec *ExecutionContext) AddRequestHeaders(headers map[string]string)
  • func (ec *ExecutionContext) Prepare() error
  • func (ec *ExecutionContext) SetupCodegenAssetsRepo() error
  • func (ec *ExecutionContext) SetupPlugins() error
  • func (ec *ExecutionContext) Spin(message string)
  • func (ec *ExecutionContext) Validate() error
  • func (ec *ExecutionContext) WriteConfig(config *Config) error
• type GlobalConfig
• type HasuraServerInternalConfig
• type MetadataMode
• type ServerAPIPaths
  • func (s ServerAPIPaths) GetQueryParams() url.Values
• type ServerConfig
  • func (c *ServerConfig) GetAdminSecret() string
  • func (c *ServerConfig) GetHasuraInternalServerConfig(client *httpc.Client) error
  • func (c *ServerConfig) GetPGDumpEndpoint() string
  • func (c *ServerConfig) GetV1GraphqlEndpoint() string
  • func (c *ServerConfig) GetV1MetadataEndpoint() string
  • func (c *ServerConfig) GetV1QueryEndpoint() string
  • func (c *ServerConfig) GetV2QueryEndpoint() string
  • func (c *ServerConfig) GetVersionEndpoint() string
  • func (c *ServerConfig) ParseEndpoint() error
• type Source

Constants

const (
	// Name of the global configuration directory
	GlobalConfigDirName = ".hasura"
	// Name of the global configuration file
	GlobalConfigFileName = "config.json"

	// Name of the file to store last update check time
	LastUpdateCheckFileName = "last_update_check_at"

	DefaultMigrationsDirectory = "migrations"
	DefaultMetadataDirectory   = "metadata"
	DefaultSeedsDirectory      = "seeds"
)

Other constants used in the package

const (
	XHasuraAdminSecret = "X-Hasura-Admin-Secret"
	XHasuraAccessKey   = "X-Hasura-Access-Key"
)

const (
	TelemetryNotice = `` /* 215-byte string literal not displayed */

)

Variables

var ErrInvalidConfigVersion error = fmt.Errorf("invalid config version")

ErrInvalidConfigVersion - if the config version is not valid

Functions

func CheckFilesystemBoundary

func CheckFilesystemBoundary(dir string) error

CheckFilesystemBiundary returns an error if dir is filesystem root

func GetAdminSecretHeaderName

func GetAdminSecretHeaderName(v *version.Version) string

func GetCommonMetadataOps

func GetCommonMetadataOps(ec *ExecutionContext) hasura.CommonMetadataOperations

func GetMigrationsStateStore

func GetMigrationsStateStore(ec *ExecutionContext) statestore.MigrationsStateStore

func GetSettingsStateStore

func GetSettingsStateStore(ec *ExecutionContext, databaseName string) statestore.SettingsStateStore

func ValidateDirectory

func ValidateDirectory(dir string) error

validateDirectory tries to parse dir for the filesRequired and returns error if any one of them is missing.

Types

type Config

type Config struct {
	// Version of the config.
	Version ConfigVersion `yaml:"version,omitempty"`

	// DisableInteractive disables interactive prompt
	DisableInteractive bool `yaml:"disable_interactive,omitempty"`

	// ServerConfig to be used by CLI to contact server.
	ServerConfig `yaml:",inline"`

	// MetadataDirectory defines the directory where the metadata files were stored.
	MetadataDirectory string `yaml:"metadata_directory,omitempty"`
	// MetadataFile defines the path in which a JSON/YAML metadata file should be stored
	MetadataFile string `yaml:"metadata_file,omitempty"`

	// MigrationsDirectory defines the directory where the migration files were stored.
	MigrationsDirectory string `yaml:"migrations_directory,omitempty"`
	// SeedsDirectory defines the directory where seed files will be stored
	SeedsDirectory string `yaml:"seeds_directory,omitempty"`

	// ActionConfig defines the config required to create or generate codegen for an action.
	ActionConfig *types.ActionExecutionConfig `yaml:"actions,omitempty"`
}

Config represents configuration required for the CLI to function

type ConfigVersion

type ConfigVersion int

ConfigVersion defines the version of the Config.

const (
	// V1 represents config version 1
	V1 ConfigVersion = iota + 1
	// V2 represents config version 2
	V2
	V3
)

func NewConfigVersionValue

func NewConfigVersionValue(val ConfigVersion, p *ConfigVersion) *ConfigVersion

NewConfigVersionValue returns ConfigVersion set with default value

func (ConfigVersion) IsValid

func (c ConfigVersion) IsValid() bool

IsValid returns if its a valid config version

func (*ConfigVersion) Set

func (c *ConfigVersion) Set(s string) error

Set sets the value of the named command-line flag.

func (*ConfigVersion) String

func (c *ConfigVersion) String() string

func (*ConfigVersion) Type

func (c *ConfigVersion) Type() string

Type returns a string that uniquely represents this flag's type.

type DefaultAPIPath

type DefaultAPIPath string

type Environment

type Environment string

Environment defines the environment the CLI is running

const (
	// DefaultEnvironment - CLI running in default mode
	DefaultEnvironment Environment = "default"
	// ServerOnDockerEnvironment - CLI running in cli-migrations image
	ServerOnDockerEnvironment = "server-on-docker"
)

type ExecutionContext

type ExecutionContext struct {
	// CMDName is the name of CMD (os.Args[0]). To be filled in later to
	// correctly render example strings etc.
	CMDName        string
	Stderr, Stdout io.Writer

	// ID is a unique ID for this Execution
	ID string

	// ServerUUID is the unique ID for the server this execution is contacting.
	ServerUUID string

	// Spinner is the global spinner object used to show progress across the cli.
	Spinner *spinner.Spinner
	// Logger is the global logger object to print logs.
	Logger *logrus.Logger

	// ExecutionDirectory is the directory in which command is being executed.
	ExecutionDirectory string
	// Envfile is the .env file to load ENV vars from
	Envfile string
	// MigrationDir is the name of directory where migrations are stored.
	MigrationDir string

	// MetadataDir is the name of directory where metadata files are stored.
	MetadataDir string
	// MetadataFile is the name of json/yaml file where metadata will be stored
	MetadataFile string

	// Seed directory -- directory in which seed files are to be stored
	SeedsDirectory string
	// ConfigFile is the file where endpoint etc. are stored.
	ConfigFile string
	// HGE Headers, are the custom headers which can be passed to HGE API
	HGEHeaders map[string]string

	// Config is the configuration object storing the endpoint and admin secret
	// information after reading from config file or env var.
	Config *Config

	// GlobalConfigDir is the ~/.hasura-graphql directory to store configuration
	// globally.
	GlobalConfigDir string
	// GlobalConfigFile is the file inside GlobalConfigDir where values are
	// stored.
	GlobalConfigFile string

	// GlobalConfig holds all the configuration options.
	GlobalConfig *GlobalConfig

	// IsStableRelease indicates if the CLI release is stable or not.
	IsStableRelease bool
	// Version indicates the version object
	Version *version.Version

	// Viper indicates the viper object for the execution
	Viper *viper.Viper

	// LogLevel indicates the logrus default logging level
	LogLevel string

	// NoColor indicates if the outputs shouldn't be colorized
	NoColor bool

	// Telemetry collects the telemetry data throughout the execution
	Telemetry *telemetry.Data

	// LastUpdateCheckFile is the file where the timestamp of last update check is stored
	LastUpdateCheckFile string

	// SkipUpdateCheck will skip the auto update check if set to true
	SkipUpdateCheck bool

	// PluginsConfig defines the config for plugins
	PluginsConfig *plugins.Config

	// CodegenAssetsRepo defines the config to handle codegen-assets repo
	CodegenAssetsRepo *util.GitUtil

	// InitTemplatesRepo defines the config to handle init-templates repo
	InitTemplatesRepo *util.GitUtil

	// IsTerminal indicates whether the current session is a terminal or not
	IsTerminal bool

	// instance of API client which communicates with Hasura API
	APIClient *hasura.Client

	// current database on which operation is being done
	Source        Source
	HasMetadataV3 bool

	// AllDatabases should be taken only incase if database isn't mentioned
	AllDatabases bool

	// after a `scripts update-config-v3` all migrate commands will try to automatically
	// move cli state from hdb_catalog.* tables to catalog state if that hasn't happened
	// already this configuration option will disable this step
	// more details in: https://github.com/hasura/graphql-engine/issues/6861
	DisableAutoStateMigration bool

	// CliExtDestinationDir is the directory path that will be used to setup cli-ext
	CliExtDestinationDir string

	// CliExtDestinationBinPath is the full path of the cli-ext binary
	CliExtDestinationBinPath string

	// CLIExtSourceBinPath is the full path to a copy of cli-ext binary in the local file system
	CliExtSourceBinPath string

	MetadataMode MetadataMode
	// contains filtered or unexported fields
}

ExecutionContext contains various contextual information required by the cli at various points of it's execution. Values are filled in by the initializers and passed on to each command. Commands can also fill in values to be used further down the line.

func NewExecutionContext

func NewExecutionContext() *ExecutionContext

NewExecutionContext returns a new instance of execution context

func (*ExecutionContext) AddRequestHeaders

func (ec *ExecutionContext) AddRequestHeaders(headers map[string]string)

func (*ExecutionContext) Prepare

func (ec *ExecutionContext) Prepare() error

Prepare as the name suggests, prepares the ExecutionContext ec by initializing most of the variables to sensible defaults, if it is not already set.

func (*ExecutionContext) SetupCodegenAssetsRepo

func (ec *ExecutionContext) SetupCodegenAssetsRepo() error

func (*ExecutionContext) SetupPlugins

func (ec *ExecutionContext) SetupPlugins() error

SetupPlugins create and returns the inferred paths for hasura. By default, it assumes $HOME/.hasura as the base path

func (*ExecutionContext) Spin

func (ec *ExecutionContext) Spin(message string)

Spin stops any existing spinner and starts a new one with the given message.

func (*ExecutionContext) Validate

func (ec *ExecutionContext) Validate() error

Validate prepares the ExecutionContext ec and then validates the ExecutionDirectory to see if all the required files and directories are in place.

func (*ExecutionContext) WriteConfig

func (ec *ExecutionContext) WriteConfig(config *Config) error

WriteConfig writes the configuration from ec.Config or input config

type GlobalConfig

type GlobalConfig struct {
	// UUID used for telemetry, generated on first run.
	UUID string `json:"uuid"`

	// Indicate if telemetry is enabled or not
	EnableTelemetry bool `json:"enable_telemetry"`

	// Indicates whether update notifications should be shown or not
	ShowUpdateNotification bool `json:"show_update_notification"`

	// CLIEnvironment defines the environment the CLI is running
	CLIEnvironment Environment `json:"cli_environment"`
}

GlobalConfig is the configuration object stored in the GlobalConfigFile.

type HasuraServerInternalConfig

type HasuraServerInternalConfig struct {
	ConsoleAssetsDir string `json:"console_assets_dir"`
}

HasuraServerConfig is the type returned by the v1alpha1/config API TODO: Move this type to a client implementation for hasura

type MetadataMode

type MetadataMode int

const (
	MetadataModeDirectory MetadataMode = iota
	MetadataModeJSON
	MetadataModeYAML
)

type ServerAPIPaths

type ServerAPIPaths struct {
	V1Query    string `yaml:"v1_query,omitempty"`
	V2Query    string `yaml:"v2_query,omitempty"`
	V1Metadata string `yaml:"v1_metadata,omitempty"`
	GraphQL    string `yaml:"graphql,omitempty"`
	Config     string `yaml:"config,omitempty"`
	PGDump     string `yaml:"pg_dump,omitempty"`
	Version    string `yaml:"version,omitempty"`
}

ServerAPIPaths has the custom paths defined for server api

func (ServerAPIPaths) GetQueryParams

func (s ServerAPIPaths) GetQueryParams() url.Values

GetQueryParams - encodes the values in url

type ServerConfig

type ServerConfig struct {
	// Endpoint for the GraphQL Engine
	Endpoint string `yaml:"endpoint"`
	// AccessKey (deprecated) (optional) Admin secret key required to query the endpoint
	AccessKey string `yaml:"access_key,omitempty"`
	// AdminSecret (optional) Admin secret required to query the endpoint
	AdminSecret string `yaml:"admin_secret,omitempty"`
	// Config option to allow specifying multiple admin secrets
	// https://hasura.io/docs/latest/graphql/cloud/security/multiple-admin-secrets/
	AdminSecrets []string `yaml:"admin_secrets,omitempty"`
	// APIPaths (optional) API paths for server
	APIPaths *ServerAPIPaths `yaml:"api_paths,omitempty"`
	// InsecureSkipTLSVerify - indicates if TLS verification is disabled or not.
	InsecureSkipTLSVerify bool `yaml:"insecure_skip_tls_verify,omitempty"`
	// CAPath - Path to a cert file for the certificate authority
	CAPath string `yaml:"certificate_authority,omitempty"`

	ParsedEndpoint *url.URL `yaml:"-"`

	HTTPClient                 *httpc.Client              `yaml:"-"`
	HasuraServerInternalConfig HasuraServerInternalConfig `yaml:"-"`
}

ServerConfig has the config values required to contact the server

func (*ServerConfig) GetAdminSecret

func (c *ServerConfig) GetAdminSecret() string

func (*ServerConfig) GetHasuraInternalServerConfig

func (c *ServerConfig) GetHasuraInternalServerConfig(client *httpc.Client) error

func (*ServerConfig) GetPGDumpEndpoint

func (c *ServerConfig) GetPGDumpEndpoint() string

func (*ServerConfig) GetV1GraphqlEndpoint

func (c *ServerConfig) GetV1GraphqlEndpoint() string

func (*ServerConfig) GetV1MetadataEndpoint

func (c *ServerConfig) GetV1MetadataEndpoint() string

GetQueryEndpoint provides the url to contact the query API

func (*ServerConfig) GetV1QueryEndpoint

func (c *ServerConfig) GetV1QueryEndpoint() string

GetQueryEndpoint provides the url to contact the query API

func (*ServerConfig) GetV2QueryEndpoint

func (c *ServerConfig) GetV2QueryEndpoint() string

func (*ServerConfig) GetVersionEndpoint

func (c *ServerConfig) GetVersionEndpoint() string

GetVersionEndpoint provides the url to contact the version API

func (*ServerConfig) ParseEndpoint

func (c *ServerConfig) ParseEndpoint() error

ParseEndpoint ensures the endpoint is valid.

type Source

type Source struct {
	Name string
	Kind hasura.SourceKind
}