add examples to all cli commands (#3475) (#3492)

cli/commands/console.go

@@ -34,7 +34,16 @@ func NewConsoleCmd(ec *cli.ExecutionContext) *cobra.Command {
   hasura console
 
   # Start console on a different address and ports:
-  hasura console --address 0.0.0.0 --console-port 8080 --api-port 8081`,
+  hasura console --address 0.0.0.0 --console-port 8080 --api-port 8081
+
+  # Start console without opening the browser automatically
+  hasura console --no-browser
+
+  # Use with admin secret:
+  hasura console --admin-secret "<admin-secret>"
+
+  # Connect to an instance specified by the flag, overrides the one mentioned in config.yaml:
+  hasura console --endpoint "<endpoint>"`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/metadata_apply.go

@@ -20,7 +20,13 @@ func newMetadataApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Use:   "apply",
 		Short: "Apply Hasura metadata on a database",
 		Example: `  # Apply Hasura GraphQL Engine metadata present in metadata.[yaml|json] file:
-  hasura metadata apply`,
+  hasura metadata apply
+
+  # Use with admin secret:
+  hasura metadata apply --admin-secret "<admin-secret>"
+
+  # Apply metadata to an instance specified by the flag:
+  hasura metadata apply --endpoint "<endpoint>"`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/metadata_clear.go

@@ -19,7 +19,13 @@ func newMetadataClearCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Aliases: []string{"reset"},
 		Short:   "Clear Hasura GraphQL Engine metadata on the database",
 		Example: `  # Clear all the metadata information from database:
-  hasura metadata clear`,
+  hasura metadata clear
+
+  # Use with admin secret:
+  hasura metadata clear --admin-secret "<admin-secret>"
+
+  # Clear metadata on a different Hasura instance:
+  hasura metadata clear --endpoint "<endpoint>"`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/metadata_diff.go

@@ -45,7 +45,13 @@ By default, shows changes between exported metadata file and server metadata.`,
   hasura metadata diff local_metadata.yaml
 
   # Show changes between metadata from metadata.yaml and metadata_old.yaml:
-  hasura metadata diff metadata.yaml metadata_old.yaml`,
+  hasura metadata diff metadata.yaml metadata_old.yaml
+
+  # Apply admin secret for Hasura GraphQL Engine:
+  hasura metadata diff --admin-secret "<admin-secret>"
+
+  # Diff metadata on a different Hasura instance:
+  hasura metadata diff --endpoint "<endpoint>"`,
 		Args: cobra.MaximumNArgs(2),
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/metadata_export.go

@@ -24,7 +24,13 @@ func newMetadataExportCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Use:   "export",
 		Short: "Export Hasura GraphQL Engine metadata from the database",
 		Example: `  # Export metadata and save it in migrations/metadata.yaml file:
-  hasura metadata export`,
+  hasura metadata export
+
+  # Use with admin secret:
+  hasura metadata export --admin-secret "<admin-secret>"
+
+  # Export metadata to another instance specified by the flag:
+  hasura metadata export --endpoint "<endpoint>"`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/metadata_reload.go

@@ -18,7 +18,13 @@ func newMetadataReloadCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Use:   "reload",
 		Short: "Reload Hasura GraphQL Engine metadata on the database",
 		Example: `  # Reload all the metadata information from database:
-  hasura metadata reload`,
+  hasura metadata reload
+
+  # Use with admin secret:
+  hasura metadata reload --admin-secret "<admin-secret>"
+
+  # Reload metadata on a different instance:
+  hasura metadata export --endpoint "<endpoint>"`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/migrate_apply.go

@@ -19,6 +19,35 @@ func newMigrateApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
 	migrateApplyCmd := &cobra.Command{
 		Use:          "apply",
 		Short:        "Apply migrations on the database",
+		Example: `  # Apply all migrations
+  hasura migrate apply
+
+  # Use with admin secret:
+  hasura migrate apply --admin-secret "<admin-secret>"
+
+  # Apply migrations on another Hasura instance:
+  hasura migrate apply --endpoint "<endpoint>"
+
+  # Mark migration as applied on the server and skip execution:
+  hasura migrate apply --skip-execution
+
+  # Apply a particular migration version only:
+  hasura migrate apply --version "<version>"
+
+  # Apply last 2 down migrations:
+  hasura migrate apply --down 2
+
+  # Apply only 2 up migrations:
+  hasura migrate apply --up 2
+
+  # Apply only a particular version
+  hasura migrate apply --type up --version "<version>"
+
+  # Rollback a particular version:
+  hasura migrate apply --type down --version "<version>"
+
+  # Rollback all migrations:
+  hasura migrate apply --down all`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/migrate_create.go

@@ -18,7 +18,13 @@ import (
 )
 
 const migrateCreateCmdExamples = `  # Setup migration files for the first time by introspecting a server:
-  hasura migrate create "init" --from-server`
+  hasura migrate create "init" --from-server
+
+  # Use with admin secret:
+  hasura migrate create --admin-secret "<admin-secret>"
+
+  # Setup migration files from an instance mentioned by the flag:
+  hasura migrate create init --from-server --endpoint "<endpoint>"`
 
 func newMigrateCreateCmd(ec *cli.ExecutionContext) *cobra.Command {
 	v := viper.New()

cli/commands/migrate_squash.go

@@ -30,7 +30,10 @@ func newMigrateSquashCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Example: `  # NOTE: This command is in PREVIEW, correctness is not guaranteed and the usage may change.
 
   # squash all migrations from version 123 to the latest one:
-  hasura migrate squash --from 123`,
+  hasura migrate squash --from 123
+
+  # Add a name for the new squashed migration
+  hasura migrate squash --name "<name>" --from 123`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v

cli/commands/migrate_status.go

@@ -21,6 +21,11 @@ func newMigrateStatusCmd(ec *cli.ExecutionContext) *cobra.Command {
 	migrateStatusCmd := &cobra.Command{
 		Use:          "status",
 		Short:        "Display current status of migrations on a database",
+		Example: `  # Use with admin secret:
+  hasura migrate status --admin-secret "<your-admin-secret>"
+
+  # Check status on a different server:
+  hasura migrate status --endpoint "<endpoint>"`,
 		SilenceUsage: true,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			ec.Viper = v