cmdx

README

cmdx

Task runner.

Project Status

This project status is alpha. The API is unstable and the test are poor.

Alternative

• Make
• npm scripts
• Task
• tj/robo
• mumoshu/variant

Overview

cmdx is the project specific task runner. Using cmdx you can manage tasks for your project such as test, build, format, lint, and release.

For example, This is the tasks for cmdx itself.

$ cmdx -l
coverage - test a package
test - test
fmt - format the go code
vet - go vet
lint - lint the go code
release - release the new version
durl - check dead links
ci-local - run the Drone pipeline at localhost

$ cmdx help release
NAME:
   cmdx release - release the new version

USAGE:
   cmdx release [arguments...]

DESCRIPTION:
   release the new version

You can make the simple shell script rich with cmdx

• cmdx supports the parse of the flag and positional arguments
• cmdx provides useful help messages

cmdx searches the configuration file from the current directory to the root directory recursively and run the task at the directory where the configuration file exists so the result of task doesn't depend on the directory you run cmdx.

Install

Download the binary from the release page.

Getting Started

Create the configuration file.

$ cmdx --init
$ cat .cmdx.yaml

Edit the configuration file and register the task hello.

$ vi .cmdx.yaml
$ cat .cmdx.yaml
---
tasks:
- name: hello
  description: hello command
  usage: hello command
  flags:
  - name: source
    short: s
    usage: source file path
    required: true
    env: NAME
  - name: switch
    type: bool
  args:
  - name: name
    usage: name
    default: bb
  environment:
    FOO: foo
  script: "echo hello {{.source}} $NAME {{if .switch}}on{{else}}off{{end}} {{.name}} $FOO" # use Go's text/template

Output the help.

$ cmdx help
NAME:
   cmdx - task runner

USAGE:
   cmdx [global options] command [command options] [arguments...]

VERSION:
   0.2.2

AUTHOR:
   Shunsuke Suzuki

COMMANDS:
   hello     hello command
   help, h   Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --config value, -c value  configuration file path
   --name value, -n value    configuration file name. The configuration file is searched from the current directory to the root directory recursively
   --init, -i                create the configuration file
   --list, -l                list tasks
   --help, -h                show help
   --version, -v             print the version

List tasks.

$ cmdx -l
hello - hello command

Run the task hello.

$ cmdx hello -s README
+ echo hello README $NAME off bb $FOO
hello README README off bb foo

$ cmdx hello -s README --switch
+ echo hello README $NAME on bb $FOO
hello README README on bb foo

$ cmdx hello --target foo
target: foo

Configuration

path	type	description	required	default
.tasks	[]task	the list of tasks	true
task.name	string	the task name	true
task.short	string	the task short name	false
task.description	string	the task description	false	""
task.usage	string	the task usage	false	""
task.flags	[]flag	the task flag arguments	false	[]
task.args	[]arg	the task positional arguments	false	[]
task.environment	map[string]string	the task's environment variables	false	{}
task.script	string	the task command. This is run by sh -c	true
flag.name	string	the flag name	true
flag.short	string	the flag short name	false
flag.usage	string	the flag usage	false	""
flag.default	string	the flag argument's default value	false	""
flag.env	string	the environment variable name which the flag value is set	false
flag.type	string	the flag type. Either "string" or "bool"	false	"string"
flag.required	bool	whether the flag argument is required	false	false
arg.name	string	the positional argument name	true
arg.usage	string	the positional argument usage	false	""
arg.default	string	the positional argument's default value	false	""
arg.env	string	the environment variable name which the argument value is set	false
arg.required	bool	whether the argument is required	false	false

script

task.script is the task command. This is parsed by Golang's text/template package. The value of the flag and positional argument can be referred by the argument name.

For example,

# refer the value of the argument "source"
script: "echo {{.source}}"

If the positional argument is optional and the argument isn't passed and the default value isn't set, the value is an empty string "".

And some special variables are defined.

name	type	description
_builtin.args	[]string	the list of positional arguments which aren't defined by the configuration args
_builtin.args_string	string	the string which joins _builtin.args by the space " "
_builtin.all_args	[]string	the list of all positional arguments
_builtin.args_string	string	the string which joins _builtin.all_args by the space " "

Example

---
tasks:
- name: hello
  flags:
  - name: source
    short: s
    description: source file path
    default: config.json
    required: false
  args:
  - name: id
    description: id
    required: true
    env: USER_ID
  environment:
    TOKEN: "*****"
  script: "bash scripts/hello.sh ${source}"

License

MIT