README.md

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 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}

---

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