{"id":13503847,"url":"https://github.com/jacobdeichert/mask","last_synced_at":"2025-10-21T04:44:37.898Z","repository":{"id":37244954,"uuid":"195581837","full_name":"jacobdeichert/mask","owner":"jacobdeichert","description":"🎭 A CLI task runner defined by a simple markdown file","archived":false,"fork":false,"pushed_at":"2025-07-15T03:25:23.000Z","size":325,"stargazers_count":1486,"open_issues_count":14,"forks_count":56,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-10-21T04:44:25.368Z","etag":null,"topics":["task-runner"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacobdeichert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-07-06T20:47:44.000Z","updated_at":"2025-10-20T15:23:18.000Z","dependencies_parsed_at":"2025-05-12T22:02:06.146Z","dependency_job_id":"28df3e0c-f865-4baf-a9c1-2759d61cd839","html_url":"https://github.com/jacobdeichert/mask","commit_stats":{"total_commits":294,"total_committers":13,"mean_commits":"22.615384615384617","dds":0.08503401360544216,"last_synced_commit":"99e6a60788db72ab5bfe7b426834bb771974bfdc"},"previous_names":["jakedeichert/mask"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/jacobdeichert/mask","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobdeichert%2Fmask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobdeichert%2Fmask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobdeichert%2Fmask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobdeichert%2Fmask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacobdeichert","download_url":"https://codeload.github.com/jacobdeichert/mask/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobdeichert%2Fmask/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280207179,"owners_count":26290616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["task-runner"],"created_at":"2024-07-31T23:00:46.972Z","updated_at":"2025-10-21T04:44:37.892Z","avatar_url":"https://github.com/jacobdeichert.png","language":"Rust","funding_links":[],"categories":["Rust","Development tools","开发工具 Development tools","others","Dev-Utilities"],"sub_categories":["Web Servers","Web服务器 Web Servers","Workflow Automation"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg height=\"180\" width=\"210\" src=\"https://user-images.githubusercontent.com/1631044/103310063-b1d79980-49e4-11eb-86e4-242c3691b0b4.png\"\u003e\n\u003c/p\u003e\n\n\n[![build status](https://github.com/jacobdeichert/mask/actions/workflows/ci.yml/badge.svg?branch=master)][github_ci]\n[![mask version](https://img.shields.io/crates/v/mask.svg)][crate]\n[![mask crate downloads](https://img.shields.io/crates/d/mask.svg)][crate]\n\n`mask` is a CLI task runner which is defined by a simple markdown file. It searches for a `maskfile.md` in the current directory which it then parses for commands and arguments.\n\nA `maskfile.md` is both a **human-readable document** and a **command definition**! Being documentation focused allows others to easily get started with your project's development setup by simply reading your `maskfile.md`. A nice advantage of using markdown is that syntax highlighting for code blocks is built-in to many editors and renderers like GitHub itself.\n\nHere's the [maskfile.md](/maskfile.md) that `mask` itself uses as an example!\n\nTo get started, follow the guide below or check out the more [advanced features](#features) `mask` has like **positional args**, **optional flags**, **subcommands**, other **scripting runtimes** and more!\n\n\n\n\n\n## Installation\n\n### Precompiled binaries\n\nHead to the [Releases page][releases] and look for the latest published version. Under **Assets** you'll see zips available for download for linux, macOS and Windows. Once downloaded, you can unzip them and then move the `mask` binary to somewhere accessible in your `$PATH` like `mv mask /usr/local/bin`.\n\n### Homebrew\n\n`mask` is available in [Homebrew][homebrew] which allows you to install it via `brew install mask`.\n\n### Cargo\n\n`mask` is published to [crates.io][crate] which allows you to install it via `cargo install mask`.\n\n### From source\n\nIf you prefer to build from source, clone this repo and then run `cargo build --release`\n\n\n\n\n\n## Getting started\n\nFirst, define a simple `maskfile.md` in your project.\n\n````markdown\n# Tasks For My Project\n\n\n\u003c!-- A heading defines the command's name --\u003e\n## build\n\n\u003c!-- A blockquote defines the command's description --\u003e\n\u003e Builds my project\n\n\u003c!-- A code block defines the script to be executed --\u003e\n```sh\necho \"building project...\"\n```\n\n\n## test\n\n\u003e Tests my project\n\nYou can also write documentation anywhere you want. Only certain types of markdown patterns\nare parsed to determine the command structure.\n\nThis code block below is defined as js which means it will be ran with node. Mask also\nsupports other scripting runtimes including python, ruby and php!\n\n```js\nconsole.log(\"running tests...\")\n```\n````\n\nThen, try running one of your commands!\n\n```sh\nmask build\nmask test\n```\n\n\n\n\n\n## Features\n\n### Positional arguments\n\nThese are defined beside the command name within `(round_brackets)`. They are required arguments that must be supplied for the command to run. The argument name is injected into the script's scope as an environment variable.\n\n**Example:**\n\n````markdown\n## test (file) (test_case)\n\n\u003e Run tests\n\n```bash\necho \"Testing $test_case in $file\"\n```\n````\n\nOptional arguments are defined within `[square_brackets]`.\n\n**Example:**\n\n````markdown\n## test [test_file]\n\n\u003e Run tests\n\n```bash\nif [[ -n \"$test_file\" ]]; then\n    echo \"Run tests in $test_file...\"\nelse\n    echo \"Running all tests....\"\nfi\n```\n````\n\n### Named flags\n\nYou can define a list of named flags for your commands. The flag name is injected into the script's scope as an environment variable.\n\n**Example:**\n\n````markdown\n## serve\n\n\u003e Serve this directory\n\n\u003c!-- You must define OPTIONS right before your list of flags --\u003e\n**OPTIONS**\n* port\n    * flags: -p --port\n    * type: string\n    * desc: Which port to serve on\n\n```sh\nPORT=${port:-8080} # Set a fallback port if not supplied\n\nif [[ \"$verbose\" == \"true\" ]]; then\n    echo \"Starting an http server on PORT: $PORT\"\nfi\npython -m SimpleHTTPServer $PORT\n```\n````\n\nYou can also make your flag expect a numerical value by setting its `type` to `number`. This means `mask` will automatically validate it as a number for you. If it fails to validate, `mask` will exit with a helpful error message.\n\n**Example:**\n\n````markdown\n## purchase (price)\n\n\u003e Calculate the total price of something.\n\n**OPTIONS**\n* tax\n    * flags: -t --tax\n    * type: number\n    * desc: What's the tax?\n\n```sh\nTAX=${tax:-1} # Fallback to 1 if not supplied\necho \"Total: $(($price * $TAX))\"\n```\n````\n\nIf you add a `choices` list, `mask` will validate if the flag value is one of them.\n\n**Example:**\n\n````markdown\n## color\n\n**OPTIONS**\n* color\n    * flags: -c --color\n    * type: string\n    * choices: RED, BLUE, GREEN\n\n```bash\nCOLOR=${color:-RED} # Fallback to RED if not supplied\necho \"Color selected = '$COLOR'\"\n```\n````\n\nIf you exclude the `type` field, `mask` will treat it as a `boolean` flag. If the flag is passed, its environment variable will be `\"true\"`, otherwise it will be unset/non-existent.\n\nImportant to note that `mask` auto injects a very common `boolean` flag called `verbose` into every single command even if it's not used, which saves a bit of typing for you. This means every command implicitly has a `-v` and `--verbose` flag already.\n\n**Example:**\n\n````markdown\n## test\n\n\u003e Run the test suite\n\n**OPTIONS**\n* watch\n    * flags: -w --watch\n    * desc: Run tests on file change\n\n```bash\n[[ \"$watch\" == \"true\" ]] \u0026\u0026 echo \"Starting in watch mode...\"\n[[ \"$verbose\" == \"true\" ]] \u0026\u0026 echo \"Running with extra logs...\"\n```\n````\n\nFlags are optional by default. If you add `required` to your flag definition, `mask` will error if it isn't supplied by the user.\n\n**Example:**\n\n````markdown\n## ping\n\n**OPTIONS**\n* domain\n    * flags: -d --domain\n    * type: string\n    * desc: Which domain to ping\n    * required\n\n```sh\nping $domain\n```\n````\n\n### Subcommands\n\nNested command structures can easily be created since they are simply defined by the level of markdown heading. H2 (`##`) is where you define your top-level commands. Every level after that is a subcommand.\n\n**Example:**\n````markdown\n## services\n\n\u003e Commands related to starting and stopping services\n\n### services start (service_name)\n\n\u003e Start a service.\n\n```bash\necho \"Starting service $service_name\"\n```\n\n### services stop (service_name)\n\n\u003e Stop a service.\n\n```bash\necho \"Stopping service $service_name\"\n```\n````\n\nYou may notice above that the `start` and `stop` commands are prefixed with their parent command `services`. Prefixing subcommands with their ancestor commands may help readability in some cases, however, it is completely optional. The example below is the same as above, but without prefixing.\n\n**Example:**\n````markdown\n## services\n\n\u003e Commands related to starting and stopping services\n\n### start (service_name)\n\n\u003e Start a service.\n\n```bash\necho \"Starting service $service_name\"\n```\n\n### stop (service_name)\n\n\u003e Stop a service.\n\n```bash\necho \"Stopping service $service_name\"\n```\n````\n\n### Support for other scripting runtimes\n\nOn top of shell/bash scripts, `mask` also supports using node, python, ruby and php as scripting runtimes. This gives you the freedom to choose the right tool for the specific task at hand. For example, let's say you have a `serve` command and a `snapshot` command. You could choose python to `serve` a simple directory and maybe node to run a puppeteer script that generates a png `snapshot` of each page.\n\n**Example:**\n\n````markdown\n## shell (name)\n\n\u003e An example shell script\n\nValid lang codes: sh, bash, zsh, fish... any shell that supports -c\n\n```zsh\necho \"Hello, $name!\"\n```\n\n\n## node (name)\n\n\u003e An example node script\n\nValid lang codes: js, javascript\n\n```js\nconst { name } = process.env;\nconsole.log(`Hello, ${name}!`);\n```\n\n\n## python (name)\n\n\u003e An example python script\n\nValid lang codes: py, python\n\n```python\nimport os\nname = os.getenv(\"name\", \"WORLD\")\nprint(\"Hello, \" + name + \"!\")\n```\n\n\n## ruby (name)\n\n\u003e An example ruby script\n\nValid lang codes: rb, ruby\n\n```ruby\nname = ENV[\"name\"] || \"WORLD\"\nputs \"Hello, #{name}!\"\n```\n\n\n## php (name)\n\n\u003e An example php script\n\n```php\n$name = getenv(\"name\") ?: \"WORLD\";\necho \"Hello, \" . $name . \"!\\n\";\n```\n````\n\n#### Windows support\n\nYou can even add powershell or batch code blocks alongside linux/macOS ones. Depending on which platform this runs on, the correct code block will be executed.\n\n**Example:**\n\n````markdown\n## link\n\n\u003e Build and link the binary globally\n\n```bash\ncargo install --force --path .\n```\n\n```powershell\n[Diagnostics.Process]::Start(\"cargo\", \"install --force --path .\").WaitForExit()\n```\n````\n\n### Automatic help and usage output\n\nYou don't have to spend time writing out help info manually. `mask` uses your command descriptions and options to automatically generate help output. For every command, it adds `-h, --help` flags and an alternative `help \u003cname\u003e` command.\n\n**Example:**\n```sh\nmask services start -h\nmask services start --help\nmask services help start\nmask help services start\n```\n\nAll output the same help info:\n\n```txt\nmask-services-start\nStart or restart a service.\n\nUSAGE:\n    mask services start [FLAGS] \u003cservice_name\u003e\n\nFLAGS:\n    -h, --help       Prints help information\n    -V, --version    Prints version information\n    -v, --verbose    Sets the level of verbosity\n    -r, --restart    Restart this service if it's already running\n    -w, --watch      Restart a service on file change\n\nARGS:\n    \u003cservice_name\u003e\n```\n\n### Running mask from within a script\n\nYou can easily call `mask` within scripts if you need to chain commands together. However, if you plan on [running mask with a different maskfile](#running-mask-with-a-different-maskfile), you should consider using the `$MASK` utility instead which allows your scripts to be location-agnostic.\n\n**Example:**\n\n````markdown\n## bootstrap\n\n\u003e Installs deps, builds, links, migrates the db and then starts the app\n\n```sh\nmask install\nmask build\nmask link\n# $MASK also works. It's an alias variable for `mask --maskfile \u003cpath_to_maskfile\u003e`\n# which guarantees your scripts will still work even if they are called from\n# another directory.\n$MASK db migrate\n$MASK start\n```\n````\n\n### Inherits the script's exit code\n\nIf your command exits with an error, `mask` will exit with its status code. This allows you to chain commands which will exit on the first error.\n\n**Example:**\n\n````markdown\n## ci\n\n\u003e Runs tests and checks for lint and formatting errors\n\n```sh\nmask test \\\n    \u0026\u0026 mask lint \\\n    \u0026\u0026 mask format --check\n```\n````\n\n### Running mask with a different maskfile\n\nIf you're in a directory that doesn't have a `maskfile.md` but you want to reference one somewhere else, you can with the `--maskfile \u003cpath_to_maskfile\u003e` option.\n\n**Example:**\n\n```sh\nmask --maskfile ~/maskfile.md \u003csubcommand\u003e\n```\n\n**Tip:** Make a bash alias for this so you can call it anywhere easily\n\n```bash\n# Call it something fun\nalias wask=\"mask --maskfile ~/maskfile.md\"\n\n# You can run this from anywhere\nwask \u003csubcommand\u003e\n```\n\n### Environment variable utilities\n\nInside of each script's execution environment, `mask` injects a few environment variable helpers that might come in handy.\n\n**`$MASK`**\n\nThis is useful when [running mask within a script](#running-mask-from-within-a-script). This variable allows us to call `$MASK command` instead of `mask --maskfile \u003cpath\u003e command` inside scripts so that they can be location-agnostic (not care where they are called from). This is especially handy for global maskfiles which you may call from anywhere.\n\n**`$MASKFILE_DIR`**\n\nThis variable is an absolute path to the maskfile's parent directory. Having the parent directory available allows us to load files relative to the maskfile itself which can be useful when you have commands that depend on other external files.\n\n### Documentation sections\n\nIf a heading doesn't have a code block, it will be treated as documentation and completely ignored.\n\n**Example:**\n\n```markdown\n## This is a heading with no script\n\nIt's useful as a place to document things like a setup guide or required dependencies\nor tools that your commands may rely on.\n```\n\n\n\n\n\n## Use cases\n\nHere's some example scenarios where `mask` might be handy.\n\n### Project specific tasks\n\nYou have a project with a bunch of random build and development scripts or an unwieldy `Makefile`. You want to simplify by having a single, readable file for your team members to add and modify existing tasks.\n\n\n### Global system utility\n\nYou want a global utility CLI for a variety of system tasks such as backing up directories or renaming a bunch of files. This is easily possible by making a bash alias for `mask --maskfile ~/my-global-maskfile.md`.\n\n\n\n\n\n## FAQ\n\n### Is `mask` available as a lib?\n\nThe [mask-parser][mask_parser] crate is available. However, it's not yet documented nor considered stable.\n\n### Where did the inspiration come from?\n\nI'm definitely not the first to come up with this idea of using markdown as a CLI structure definition.\n\nMy frustrations with `make`'s syntax is what led me to search for other options. I landed on [just][just] for awhile which was a pretty nice improvement. My favourite feature of `just` is its support for other language runtimes, which is why `mask` also has this ability! However, it still didn't have some features I wanted like nested subcommands and multiple optional flags.\n\nAt some point in my searching, I came across [maid][maid] which is where most of the inspiration for `mask` comes from. I thought it was brilliant that markdown could be used as a command definition format while still being so readable.\n\nSo why did I choose to rebuild the wheel instead of using `maid`? For one, I preferred installing a single binary, like `just` is, rather than installing an npm package with hundreds of deps. I also had a few ideas on how I could improve upon `maid` which is why `mask` supports multiple levels of nested subcommands as well as optional flags and positional args. Also... I just really wanted to build another thing with Rust :)\n\nI also need to mention [clap][clap] and [pulldown-cmark][cmark] which are really the core parts of `mask` that made it so easy to create.\n\n\n\n\n\n## Contributing\n\nCheck out our [Contribution Guidelines](CONTRIBUTING.md) before creating an issue or submitting a PR 🙌\n\nAlso, please review and follow the rules within our [Code of Conduct](CODE_OF_CONDUCT.md) 🙂\n\n\n\n\n\n## Author\n\nJacob Deichert with the help of contributors.\n\n\n\n\n\n[github_ci]: https://github.com/jacobdeichert/mask/actions?query=workflow%3ACI\n[mask_parser]: https://crates.io/crates/mask-parser\n[homebrew]: https://formulae.brew.sh/formula/mask\n[crate]: https://crates.io/crates/mask\n[releases]: https://github.com/jacobdeichert/mask/releases\n[2]: https://github.com/jacobdeichert/mask/issues/5\n[maid]: https://github.com/egoist/maid\n[just]: https://github.com/casey/just\n[clap]: https://github.com/clap-rs/clap\n[cmark]: https://github.com/raphlinus/pulldown-cmark\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobdeichert%2Fmask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacobdeichert%2Fmask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobdeichert%2Fmask/lists"}