https://github.com/metaory/mxflow-cli
:zap: A Beautiful, Friendly, General purpose CLI task runner
https://github.com/metaory/mxflow-cli
build-tool ci cicd cli command-line console makefile mxflow pipeline script-engine task-manager task-runner terminal tooling workflow workflow-automation workflow-engine
Last synced: 7 months ago
JSON representation
:zap: A Beautiful, Friendly, General purpose CLI task runner
- Host: GitHub
- URL: https://github.com/metaory/mxflow-cli
- Owner: metaory
- License: mit
- Created: 2022-09-24T05:54:16.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-25T19:20:16.000Z (about 2 years ago)
- Last Synced: 2024-04-20T15:55:22.835Z (over 1 year ago)
- Topics: build-tool, ci, cicd, cli, command-line, console, makefile, mxflow, pipeline, script-engine, task-manager, task-runner, terminal, tooling, workflow, workflow-automation, workflow-engine
- Language: JavaScript
- Homepage: https://npmjs.com/package/mxflow
- Size: 2.67 MB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
Why |
Installation |
Usage |
Config |
Videos
:zap: A Beautiful, Friendly, General purpose CLI task runner :rocket:
`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:
```bash
sudo npm i -g mxflow
```
Setup shell tab completion:
```bash
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
```bash
mxflow [] [] []
```
# CLI Options
```markdown
init | init sample configuration
trigger | 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;
```bash
mxflow # or mxf
```
To bypass _confirmation_ prompts;
```bash
mxflow --force
```
To interactively select a workflow to trigger;
```bash
mxflow trigger
```
To trigger a particular workflow interactively;
```bash
mxflow trigger create-flight
```
To trigger a particular workflow with arguments;
```bash
mxflow trigger create-flight --taskId my-tsk --description my-desc --force
```
---
# Config
`.mxflow/config.yml`
> `mxflow trigger foobar --foo fval --bar bar-xorg`
```yaml
# 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](https://github.com/metaory/mxflow-cli/wiki/Git-Workflow-Sample) 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](https://github.com/metaory/mxflow-cli/wiki/Git-Workflow-Sample)
---
# Roadmap
- [x] project based config file
- [ ] plugin system for dynamic lists
- [x] argument mode
- [x] argument autocomplete
- [x] support `.env` file import
---
Videos
### Installation
### Interactive Usage
### Argument Usage
---
## License
[MIT](LICENSE)