Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mumoshu/variant

Wrap up your bash scripts into a modern CLI today. Graduate to a full-blown golang app tomorrow.
https://github.com/mumoshu/variant

Last synced: 20 days ago
JSON representation

Wrap up your bash scripts into a modern CLI today. Graduate to a full-blown golang app tomorrow.

Awesome Lists containing this project

README 

        



# Variant



![image](https://user-images.githubusercontent.com/22009/51234992-b1899380-19b1-11e9-83c3-dbfdb1517b1c.png)



##### Build modern command line applications in **YAML** and **any scripting language** of your choice, and eventually enhance it with golang



[![CircleCI](https://circleci.com/gh/mumoshu/variant.svg?style=svg)](https://circleci.com/gh/mumoshu/variant)



Integrations: [GitHub Actions](https://github.com/mumoshu/github-actions/tree/master/variant)






```console

$ cat < main.go

package main

import "github.com/mumoshu/variant/cmd"

func main() {

    cmd.YAML(\`

$(cat yourcmd)

\`)

}

EOF



$ cat < Gopkg.toml

[[constraint]]

  name = "github.com/mumoshu/variant"

  version = "v0.24.0"

EOF

```



And then build with the standard golang toolchain:



```console

$ dep ensure

$ go build -o dist/yourcmd .

```



```console

$ ./mycli --target variant

Hello variant!

```



It is recommended to version-control the produced `Gopkg.toml` and `Gopkg.lock` because it is just more straight-forward than managing embedded version of em in the shell snippet.



It is NOT recommended to version-control `main.go`. One of the benefits of Variant is you don't need to recompile while developing. So it is your Variant command written in YAML that should be version-controlled, rather than `main.go` which is necessary only while releasing.



# How it works



Variant is a framework to build a CLI application which becomes the single entry point to your DevOps workflows.



It consists of:



* YAML-based DSL

  * to define a CLI app's commands, inputs

  * which allows splitting commands into separate source files, decoupled from each others

* Ways to configure your apps written using Variant via:

  * defaults

  * environment variables

  * command-line parameters

  * application specific configuration files

  * environment specific configuration files

* DI container

  * to implicitly inject required inputs to a commands from configuration files or outputs from another commands

  * to explicit inject inputs to commands and its dependencies via command-line parameters



# Features



- Default Command

- Task grouping

- Dependency injection



## Default Command



The top-level `script` is executed whenever there's no sub-task that matches the provided command-line arguments.



In the below example, `./mycmd bar` runs the task `bar`, while `./mycmd foo bar` fails with an "unknown command" error:



```

tasks:

  bar:

    script: |

      echo bar

```



While in the next example, `./mycmd foo bar` runs the root task(=the top-level `script`):



```

script: |

  echo {{ index .args 0 }}



tasks:

  bar:

    script: |

       echo bar

```



## Dependency injection



An input named `myinput` for the task `mytask` can be one of follows, in order of precedence:



* Value of the command-line option `--myinput`

* Value of the configuration variable `mytask.myinput`

  * from the environment specific config file: `config/environments/.yaml`

  * from the common config file: `.yaml`(normally `var.yaml`)

* Output of the task `myinput`



## Environments



You can switch `environment` (or context) in which a task is executed by running `var env set `.



```

$ var env set dev

$ var test

#=> reads inputs from var.yaml + config/environments/dev.yaml



$ var env set prod

$ var test

#=> reads inputs from var.yaml + config/environments/prod.yaml

```



## Environment Variables



`variant` takes a few envvars for configuration.



`VARIANT_RUN`: Additional command-line arguments to be added to the actual args. For instance, `VARIANT_RUN="bar baz" variant foo --color=false` is equivalent to `variant foo --color=false bar baz`.



`VARIANT_RUN_TRIM_PREFIX`: Prefix to be removed from the `VARIANT_RUN`. For intance, `VARIANT_RUN="/myslashcmd --foo=bar" variant mycmd` is equivalent to `variant mycmd --foo=bar`.



`VARIANT_GITHUB_COMMENT(_ON_[SUCCESS|FAILURE])`: (GitHub Actions v2 only) When this variables is set to a non-empty value, variant tries to obtain the "source" GitHub issue/pull request that triggered the run, and sends a issue/pr comment containing the result. Great for giving feedbacks to whom run the variant task from e.g. GitHub comment. 



# FAQ



Please see the collection of answered questions in our [GitHub issues labeled "question"](https://github.com/mumoshu/variant/issues?utf8=%E2%9C%93&q=label%3Aquestion+).



# Integrations and useful companion tools



- Use [liujianping/job](https://github.com/liujianping/job) for timeouts, retries, scheduled runs, etc.

- Use [davidovich/summon](https://github.com/davidovich/summon) to bundle assets into your variant command by using the golang module system and `gobin`



# Alternatives



* [go-task/task](https://github.com/go-task/task)

* [tj/robo](https://github.com/tj/robo)

* [goeuro/myke](https://github.com/goeuro/myke)

* [kevgo/morula](https://github.com/kevgo/morula) - task runner for monorepos



# Interesting Readings



* [How to write killer DevOps automation workflows](http://techbeacon.com/how-write-killer-devops-automation-workflows)

* [progrium/bashstyle: Let's do Bash right!](https://github.com/progrium/bashstyle)

* [ralish/bash-script-template: A best practices Bash script template with many useful functions](https://github.com/ralish/bash-script-template)



# Future Goals



* Runners to run tasks in places other than the host running your Variant app

  * Docker

  * Kubernetes

  * etc

* Tools/instructions to package your Variant app for easier distribution

  * Single docker image containing

    * all the scripts written directly in the yaml

    * maybe all the scripts referenced from scripts in the yaml

    * maybe all the commands run via the host runner

* Integration with job queues

  * to ensure your tasks are run reliably, at-least-once, tolerating temporary failures



# License



Apache License 2.0



# Attribution



We use:



- [semtag](https://github.com/pnikosis/semtag) for automated semver tagging. I greatly appreciate the author(pnikosis)'s effort on creating it and their kindness to share it!