how to set up a global maskfile for system tasks

Create a maskfile.md in your home directory and use an alias like 'alias wask="mask --maskfile ~/maskfile.md"' to run commands from anywhere, as suggested in the README's tip for global utilities.

mask vs just for task running

Mask offers nested subcommands and markdown-based readability, while Just focuses on simplicity and speed with a dedicated syntax. Mask is better for documentation-heavy workflows, but Just might be preferred for minimal overhead and faster execution in script-heavy projects.

how to handle errors in mask scripts

Mask inherits the script's exit code, so you can use standard shell error handling (like && or set -e). For example, chaining commands with && will stop on the first error, as shown in the 'ci' command example in the README.

can mask run tasks in parallel

No, mask executes commands sequentially within a script. For parallel execution, you'd need to implement it manually in the script using language-specific features (e.g., background processes in shell), which isn't built into mask itself.

how to use environment variables in mask scripts

Mask injects arguments and flags as environment variables (e.g., $port for a --port flag) and provides utilities like $MASKFILE_DIR for path resolution. You can also set custom env vars within the script, as demonstrated in the examples.

mask integration with CI/CD like GitHub Actions

Mask can be installed via precompiled binaries or package managers, and you can run mask commands directly in CI scripts. However, it lacks native plugins or specific integrations, requiring manual setup similar to other CLI tools.

Open-Awesome

mask

MITRustmask/0.11.7

A CLI task runner that uses a markdown file as both human-readable documentation and command definitions.

GitHub

1.6k stars60 forks0 contributors

What is mask?

Mask is a CLI task runner that allows developers to define and run project automation commands through a simple markdown file. It replaces complex Makefiles or shell scripts with a readable, documentation-focused format that supports multiple scripting languages and structured command-line arguments.

Target Audience

Developers and teams looking for a lightweight, readable alternative to Make or Just for managing project-specific tasks, build scripts, and development workflows.

Value Proposition

Mask combines executable commands with human-readable documentation in a single markdown file, reducing the learning curve for new contributors and supporting a wide range of scripting languages for flexible automation.

Overview

🎭 A CLI task runner defined by a simple markdown file

Use Cases

Best For

Replacing unwieldy Makefiles with a more readable markdown-based task runner
Creating global system utilities for backup, file management, or other repetitive tasks
Documenting project setup and development commands alongside their implementations
Building CLI tools with nested subcommands and validated arguments
Writing automation scripts in multiple languages (shell, Python, Node.js, etc.) within a single file
Simplifying onboarding by providing executable documentation for project workflows

Not Ideal For

Projects requiring interactive CLI features like real-time prompts or complex GUI integration
Environments where minimizing external dependencies is critical, as mask requires language runtimes for non-shell scripts
Teams needing extensive IDE integration or advanced tooling beyond basic command execution

Pros & Cons

Pros

Readable Command Definitions

Commands are defined in markdown, making the maskfile.md both executable and human-readable documentation, as emphasized in the README's focus on combining command running with living documentation.

Multi-Language Scripting Support

Supports scripts in shell, Node.js, Python, Ruby, PHP, Lua, Swift, PowerShell, and Batch, allowing task-specific language choice, demonstrated with code examples for each runtime in the Features section.

Structured CLI Features

Provides positional arguments, named flags with validation (like types and choices), and nested subcommands using markdown headings, enabling complex CLI structures without custom parsing, as detailed in the README.

Automatic Help Generation

Generates help output from command descriptions and options, with built-in -h/--help flags, reducing manual documentation effort, shown in the examples for commands like 'services start'.

Cons

External Runtime Dependencies

For scripts in languages like Python or Node.js, mask requires those runtimes to be installed separately, adding setup overhead and potential version management issues, which isn't ideal for minimal environments.

Markdown Parsing Fragility

Command definitions rely on markdown syntax (headings, code blocks), making them susceptible to parsing errors if the file is malformed, unlike dedicated configuration formats that offer more robustness and error handling.

Immature Library Ecosystem

The mask-parser crate is available but undocumented and not stable, limiting integration into custom tools or extensions, as admitted in the FAQ section, which hinders advanced use cases.

Cross-Platform Scripting Overhead

Supporting multiple platforms requires maintaining separate code blocks (e.g., bash and PowerShell), which can complicate script maintenance and increase file size, as noted in the Windows support example.

Open Source Alternative To

mask is an open-source alternative to the following products:

make

Make (or GNU Make) is a build automation tool that automatically builds executable programs and libraries from source code by reading Makefiles.

Maid

Maid is a task runner and automation tool that uses Markdown files to define and execute tasks, often used for project automation and scripting.

Just

Just is a command-line tool for saving and running project-specific commands, providing a simple alternative to complex build systems or package.json scripts.

Frequently Asked Questions

Related Projects

goose

an open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM

Stars47,610

Forks5,018

Last commit2 days ago

just

🤖 Just a command runner

Stars34,220

Forks795

Last commit1 day ago

A Git-compatible VCS that is both simple and powerful

Stars29,487

Forks1,081

Last commit21 hours ago

mise

dev tools, env vars, task runner

Stars29,236

Forks1,185