Why | Config | Installation | Usage | Options

⚡ A Friendly, General purpose CLI task runner 🚀

mxflow is a CLI task runner which is defined by 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 just not friendly.

Major features

• Interactive first - works with/without arguments; prompt missing args
• Extensive config - group commands under a workflow, use arguments export value 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

Config

.mxflow/config.yml

mxflow trigger foobar --foo fval --bar 222

version: 0.60.0
workflows:
  foobar:
    description: example placeholder
    args:
      - name: foo
        type: string
      - name: bar
        type: number
        default: 123
        export: barx
    steps:
      - echo {foo} world
      - echo goodbye {foo} {barx} cruel world
      - confirm echo {barx} goodbye
      - echo AWS_PROFILE $AWS_PROFILE
      - 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

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

steps - list of commands to run

steps[*] - the command to run

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: currently there are few special git commands: checkout-branch, list-logs, log-bugtracker. check wiki for usage example

Config Variables

echo foo {variable} bar:

• args - export or name
• environment - system environment variables
• .env - variables defined in the .env file

Real-world Use case: git-workflow

Requirements

• Node 16+

Installation

npm i -g mxflow
mxflow --setup-completion

or

npx mxflow

Usage

mxflow [<action>] [<args>]

Options

init                    | init sample configuration
trigger <workflow-name> | non-interactive workflow trigger
version                 | show version
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

Example

mxflow # or mxf
mxflow trigger foobar --verbose
mxflow trigger feature --taskId xorg --description zelda
mxflow --no-catch-git # to bypass initial git checks

Roadmap

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

⚠️ MXFlow is in an early state of release. Breaking changes may be made to APIs/core structures as the tool matures.

License

MIT