Why | Installation | Usage | Config | Videos

⚡ A Beautiful, Friendly, General purpose CLI task runner 🚀

mxflow is a CLI task runner which configured via a YAML config file.

It searches for a .mxflow/config.yml in the current directory and parent directories recursively up which it then parses for commands and arguments

Why?

• Internal processes can get complicated or too repetitive.

• It's hard to streamline complex workflows across teams.

• Existing task-runners are too focused on a specific use-case/environment or have complicated config files or are not friendly!

---

Major Features

• Interactive first - works with/without arguments; prompt missing arguments
• Extensive config - group commands under a workflow, use argument variables in commands
• Shell completion - dynamic shell completion based on the closest config file
• Confirmation - add confirm prefix to any step command to add confirmation prompt
• Project / System config - searches for a .mxflow/config.yml in the current directory and parent directories recursively up, so you can have different configs based on the current directory

---

Requirements

• Node 16+

---

Installation

Install the package, globally:

sudo npm i -g mxflow

Setup shell tab completion:

mxflow --setup-completion

make sure to run this command once, in case you have ran this command more than once, you can run the mxflow --clean-completion to clean.

Usage

mxflow [<action>] [<args>] [<flags>]

CLI Options

 init | init sample configuration
trigger <workflow-name> | non-interactive workflow trigger
view | view config
edit | edit config
reset | reset config
version, --version | show version
help, --help | help menu
-v, --verbose | verbose logs
-F, --force | force bypass confirmation prompts
--no-catch-git | bypass initial git checks
--setup-completion | setup shell tab completion
--clean-completion | cleanup tab completion`,

Examples

For a fully interactive experience;

mxflow # or mxf

To bypass confirmation prompts;

mxflow --force

To interactively select a workflow to trigger;

mxflow trigger

To trigger a particular workflow interactively;

mxflow trigger create-flight

To trigger a particular workflow with arguments;

mxflow trigger create-flight --taskId my-tsk --description my-desc --force

---

Config

.mxflow/config.yml

mxflow trigger foobar --foo fval --bar bar-xorg

# The CLI Versionversion: 0.60.0# The milliseconds to wait between commandssleep: 1000# Should exit upon first error code facedexit_on_error: false# Config Workflowsworkflows:
# Workflow namefoobar:
# Workflow descriptiondescription: example placeholder# Checks to run before workflow. Possible checks are: [git-clean]checks:
- git-clean# Variables to collect to be available later on stepsargs:
# Variable name
- name: foo# Variable type. Possible types are: [string, number]type: string
- name: bartype: string# Regex to test argument inputregex: ^bar+\w# The default value for the variabledefault: barxorg# Set a different name for the variableexport: barx# Steps are list of commands to executesteps:
# Variable name or its export are available with braces
- echo {foo} world# Variable export
- echo goodbye {foo} {barx} cruel world# the `current-branch` is a special variable; always available
- echo git branch is {current-branch}# Appending `confirm` will add a confirmation step before the following command
- confirm shutdown -h now# Its possible to use system environment variable; resolved at runtime
- echo AWS_PROFILE $AWS_PROFILE# Or use braces syntax; it will resolve before execution
- echo AWS_PROFILE {AWS_PROFILE}

---

Config Reference

version - config version

exit_on_error - (optional) should exit on any command with a non-zero exit code, default is false

sleep - (optional) adds a delay between each command, default is 1000

workflows - object with workflows

Workflow Reference

description - workflow description

checks - checks to run before workflow. Possible checks are: [git-clean]

args - list of arguments

args[*].name - what user inputs as argument

args[*].type - validation type; string | number

args[*].export - (optional) the exported variable, default is args[*].name

args[*].default - (optional) the default value, if any

args[*].regex - (optional) validation pattern

steps - list of commands to run

steps[*] - the command to run, any shell command string, with some specials commands

note: you can write a cd pre-step to change cwd of the following command

note: you can add a confirm prefix to add confirmation prompt

note: at the moment there are some git commands: checkout-branch, list-logs, log-bugtracker. Check wiki for usage example

Config Variables

Example: echo foo {variable} bar

• Argument variables
  • args - export or name
• Environment variables
  • environment - system environment variables
  • .env - variables defined in the .env file
• git variables
  • {current-branch} - current active branch
• workflow
  • {workflow} - current active workflow

Real-world Use-cases

• git-workflow

---

Roadmap

• project based config file
• plugin system for dynamic lists
• argument mode
• argument autocomplete
• support .env file import

---

Videos

Installation

Interactive Usage

Argument Usage

---

License

MIT