0.64.5 • Public • Published

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


  • 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


  • Node 16+


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.


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


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



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
  # Workflow name
    # Workflow description
    description: example placeholder
    # Checks to run before workflow. Possible checks are: [git-clean]
      - git-clean
    # Variables to collect to be available later on steps
      # 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
      # 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
        # Or use braces syntax; it will resolve before execution

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


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




Interactive Usage


Argument Usage




Package Sidebar


npm i mxflow

Weekly Downloads






Unpacked Size

53.6 kB

Total Files


Last publish


  • metaory