henzeb / cmdr
A framework in pure bash
Maintainers
Requires
- php: >=8.0
README
A pure Bash framework for crafting beautiful, reusable commands.
Every project accumulates scripts for mundane tasks — spinning up local environments, managing Kubernetes clusters, or running a test suite in a loop to catch flaky tests. They work, but they sprawl. New team members have no idea what exists, what arguments a script expects, or what it will actually do. The answer is usually a wall of --help text nobody wrote, or a wiki page nobody updated.
Tools like bashly and bash-it solve adjacent problems: bashly generates CLI apps from YAML but requires a build step and a Ruby runtime; bash-it is a personal shell framework for customizing your own environment, not for sharing commands with a team. Neither gives you a way to distribute a consistent set of commands through your project's own dependencies.
cmdr does. Install it per-project via Composer, add your functionality in the project's .cmdr directory and your whole team gets the same commands after composer install — with argument parsing, validation, interactive prompts, tab completion, and help pages built in. No build step. No runtime beyond Bash.
Features
- Modules — organize commands into namespaced modules; add, override, or extend them per-project or globally
- No build step — pure Bash, sourced directly; requires Bash 4.3+
- Declarative args & options — define positional arguments and flags with types, defaults, and descriptions
- Validation — 30+ built-in rules with support for custom rules and named groups
- Interactive input — built-in prompts (text, confirm, select, multiselect) with validation support
- Shell completion — tab completion for Bash, Zsh, and Fish
- Hooks — event-driven extension points for modules
- Scaffold generator —
cmdr make modulebootstraps a new module from a template - Composer-distributed — install globally or per-project like any other package
Installation
Requirements: Bash 4.3+. macOS ships with Bash 3.2 — install a modern version via Homebrew (brew install bash). Composer is required to install cmdr.
Global (available system-wide):
composer global require henze/cmdr
Make sure Composer's global bin directory is on your PATH. Run composer global config bin-dir --absolute to find the path, then add it to your shell config.
Per-project (shared with your team as a Composer dependency):
composer require --dev henze/cmdr ./vendor/bin/cmdr alias # optional: creates a shell alias for this project
See docs/installation.md for full PATH setup instructions and how to combine both approaches.
Usage
cmdr help # list all available commands cmdr <module> help # list commands in a module cmdr <module> <subcommand> # run a command cmdr <module> <subcommand> --help # show command help