aah Console Commands

Introduced in v0.12.0. This document provides the insight into aah Console module aahframe.work/console usage.

Table of Contents

• Overview
• Supported Flag Types & Accessing Value
• Creating User-Defined Command
• Creating Sub-Commands
• Adding User-Defined Command
• Customizing version and help Flag Description
• Running console command using aah CLI

Overview

In v0.12.0 release, aah introduced the console commands feature. Easily add N no. of user-defined behavior(s) as a console command into aah application binary.

By default application binary have few important reserved commands -

• Command run - Runs application server
• Command vfs - Provides access to app VFS instance to interact with it
• Command help - Shows a list of commands or help for one command

Console module aahframe.work/console is a type aliased package using github.com/urfave/cli. Important thing in this design approach is to keep decouple from third-party library also have ability introduce in-home library (if need be) with retaining all capabilities. From aah user prespective everything is smooth.

Supported Flag Types & Accessing Value

Console command supports following flag types -

• console.StringFlag
• console.BoolFlag
• console.IntFlag
• console.Int64Flag
• console.Float64Flag
• console.IntSlice
• console.StringSlice

Example

// Defining flag
console.StringFlag{
    Name:  "envprofile, e",     // long and short posix flag name
    Value: "dev",               // default flag value
    Usage: "Environment profile name to activate (e.g: dev, qa, prod)",
}

// Accessing flag value with action function
ctx.String("envprofile") // or ctx.String("e")

Creating User-Defined Command

Creating user-defined command is very easy. Let’s say we have directory/package under <app-base-dir>/app/commands-

// User-defind `sample` command
var Sample = console.Command{
	Name:    "sample",
	Aliases: []string{"s"},
	Usage:   "This is sample user-defined command for aah application",
	Description: `This is long multi-line description about sample command

  Example:
    <app-binary> sample --message "hello sample command"
  `,
	Flags: []console.Flag{
		console.StringFlag{
			Name:  "message, m", // long and short flag name
			Usage: "Greeting message to sample command",
		},
	},
	Action: func(ctx *console.Context) error {
		fmt.Println("Welcome to sample command")
		fmt.Println("Greetings:", ctx.String("message"))
		return nil
	},
}

Creating Sub-Commands

Creating sub commands are very easy. Let’s say we have directory/package under <app-base-dir>/app/commands-

// Sample Command with sub-command 'greet'
var Sample = console.Command{
	Name:    "sample",
	Aliases: []string{"s"},
	Usage:   "This is sample user-defined command for aah application",
	Description: `This is long multi-line description about sample command

  Example:
    <app-binary> sample <sub-command>
  `,
	Subcommands: []console.Command{
		{
			Name:    "greet",
			Aliases: []string{"g"},
			Usage:   "This is greet sub command for sample command",
			Description: `This long multi-line description about greet sub-command.
		
      Example:
        <app-binary> s g -m "hello greet sub-command"
			  <app-binary> sample greet --message "hello greet sub-command"
		  `,
			Flags: []console.Flag{
				console.StringFlag{
					Name:  "message, m", // long and short flag name
					Usage: "Greeting message",
				},
			},
			Action: func(ctx *console.Context) error {
				fmt.Println("Welcome to greet sub-command")
				fmt.Println("Greetings:", ctx.String("message"))
				return nil
			},
		},
	},
}

Adding User-Defined Commands

Adding user-defined commands into aah application binary.

func init() {
  app := aah.App()
  if err := app.AddCommand(Command1, Command2, Command3); err != nil {
    app.Log().Error(err)
  }
}

Customizing version and help Flag Description

func init() {
  console.VersionFlagDesc("your custom version flag description")
  console.HelpFlagDesc("your custom help flag description")
}

// Sample Output:
// --------------
// Global Options:
//   --help, -h     your custom help flag description
//   --version, -v  your custom version flag description

Running console command using aah CLI

Typically aah user could run console command by building aah application and executing application binary.

It just aah CLI provides handy command that does it for you.

# Syntax
aah runcmd <command> <arguments>

# Example of running command `vfs`
aah runcmd vfs find --pattern "conf$"