Mxflow NPM | npm.io

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
version, --version | show version
help, --help | help menu
-v, --verbose | verbose logs
-F, --force | bypass confirmation prompts
--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 Version
version: 0.60.0
# The milliseconds to wait between commands
sleep: 1000
# Should exit upon first error code faced
exit_on_error: false
# Config Workflows
workflows:
  # Workflow name
  foobar:
    # Workflow description
    description: example placeholder
    # Checks to run before workflow. Possible checks are: [git-clean]
    checks:
      - git-clean
    # Variables to collect to be available later on steps
    args:
      # Variable name
      - name: foo
        # Variable type. Possible types are: [string, number]
        type: string
      - name: bar
        type: string
        # Regex to test argument input
        regex: ^bar+\w
        # The default value for the variable
        default: barxorg
        # Set a different name for the variable
        export: barx
    # Steps are list of commands to execute
    steps:
      # 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}

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

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

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