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 module bootstraps 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

Documentation

• Installation
  • Requirements
  • Installing globally
  • Installing per project
  • Combining both
• Configuration
  • Config file locations
  • Using global flags
  • Available config variables
• Directory Structure
  • The project directory
  • The global directory
  • Load order
• Modules
  • Choosing a layout
  • Search paths
  • Creating a module
  • Adding submodules
  • Declaring dependencies with cmdr::use
  • Conditional loading
  • Registering aliases
  • Locking and hiding
  • Registering root commands
  • Native help
  • Finding the project root
  • Dynamic tab completion
  • Distributing a module as a Composer package
• Hooks
  • Registering a listener
  • Implementing listeners
  • Firing a hook
  • Discovering hook files
  • Naming hooks
  • Handling return values
  • Bootstrap hooks
• Arguments & Options
  • Declaring arguments
  • Retrieving values
  • Passthrough arguments
  • Using global options
• Output
  • Output helpers
  • Progress bar
  • Task list
  • Configuring output
• Input
  • Prompt helpers
  • The description argument
  • Using input with validation
• Shell Completion
  • Installing completion
  • What gets completed
  • Registering dynamic completers
• Validation
  • Creating named validator groups
  • Validating interactive input
  • Built-in rules
  • Writing custom rules
  • Overriding error messages
• Composer utilities
  • Checking for a package
  • Inspecting versions
• JSON utilities
  • Extracting a value
• Shell helpers
  • Writing to the shell config
  • Checking the environment
• Callers
  • Re-invoking cmdr
  • Resolving external commands
  • Registering candidates
• Scaffolding
  • Scaffolding a module
  • Generated files
  • Registering a custom scaffold type
  • Using the scaffold API
  • Placeholder substitution
• Shipped modules
  • init
  • docker