bashly-framework/bashly
65.7
Adequate · 6 November 2026
2.8k
lines of production code
Ruby
primary language
4
measurements over time
What this system is
Bashly is a Ruby-based command-line interface generator that creates robust, standalone shell scripts from YAML configuration files. It supports complex CLI structures including nested subcommands, argument validation, shell completions, and extensible command delegation. The system provides a rich standard library for common tasks like configuration management, color output, and documentation rendering, while enforcing strict configuration validation to ensure generated scripts are reliable and maintainable.
How it got here
2019–2021 — Bashly 2.0 major overhaul
74 changes.
This period marks the development of Bashly 2.0.0, featuring a comprehensive CLI overhaul with new commands, stricter configuration validation, and a migration from ERB to the GTX templating engine. The release introduces a robust library system for reusable code snippets, native shell completions, and extensive support for complex argument parsing and validation. The work also included significant internal refactoring of model classes and expanded test coverage to ensure stability across these major architectural changes.
2022–2023 — library expansion and documentation rendering
62 changes.
This period focused on significantly expanding the Bashly standard library with new modules for INI configuration management, input validation, and execution hooks. It also introduced comprehensive documentation generation capabilities, adding support for Markdown and man page output alongside extensive new examples and test coverage for these features.
2024–2026 — introspection, completions, and debugging features
29 changes.
This period focused on expanding the CLI generator's capabilities by introducing private visibility controls for help output, advanced runtime shell completions, and a stacktrace debugging library. The work was heavily supported by comprehensive test fixtures and examples covering argument parsing, variable scoping, and error handling to ensure robust code generation.
Features
Add INI and config parsing libraries to Bashly standard library
The Bashly standard library now includes \ini.sh\ and \config.sh\, providing functions to load, parse, and save INI configuration files. The \ini\ module exposes a global associative array for direct key-value access (supporting sections) and handles environment variable substitution in values via \envsubst\. The \config\ module wraps this with a simpler API (\config\_get\, \config\_set\, \config\_del\, etc.) that automatically manages loading and saving, allowing users to easily integrate configuration management into their Bash scripts.
examples/config/src/lib · high confidence
Add INI file handling example with environment variable support
This location introduces a new example application (\configly\) that demonstrates how to read, write, and manage INI configuration files using the Bashly standard library. The included \src/lib/ini.sh\ library provides functions to load INI files into an associative array, save changes back to disk, and supports optional sections. A key behavioral detail is that values containing shell variable syntax (e.g., \$VAR\) are automatically processed via \envsubst\ during loading, allowing environment variables to be used within INI values. The example includes commands for listing, getting, setting, and deleting configuration keys.
examples/ini · high confidence
Add STDIN reading example
A new example demonstrating how to read from STDIN has been added to the examples/stdin directory. It includes a bashly configuration where arguments default to '-' to indicate STDIN input, a generated shell script that uses 'cat' to handle both file paths and STDIN, and a test script to verify the behavior.
examples/stdin · high confidence
Add YAML example demonstrating standard library integration
A new example located in examples/yaml demonstrates how to use the Bashly standard library to read YAML files. This includes a sample application that loads YAML settings into shell variables, supports optional prefixes for variable names, and allows filtering for specific variables. The example provides the necessary configuration (bashly.yml), a sample settings file, the generated root command script, and a test script to verify the functionality.
examples/yaml · high confidence
Add advanced runtime shell completion example
The examples/completions-advanced directory now provides a complete reference implementation for configuring advanced runtime shell completions. This example demonstrates how to enable full completions via settings.yml and configure specific behaviors for commands and flags, including static candidates, dynamic external command execution (e.g., git branch), internal function-based dynamic candidates, and options to prevent trailing spaces or restrict completions to files and directories. It includes the necessary bashly configuration, shell script implementations, and a test suite to verify the generated completion scripts for both Bash and Zsh.
examples/completions-advanced · high confidence
Add argfile example demonstrating autoloaded flag defaults
The \examples/argfile\ directory now includes a complete example showing how to use the \argfile\ command option to autoload flag defaults from a file (\.download\). The example demonstrates that boolean flags, flag values with spaces, and repeatable/unique flags can be defined in the argfile, while unknown flags and non-flag lines are safely ignored. It also includes the necessary \bashly.yml\ configuration, a generated shell script, and a test suite to verify the behavior.
examples/argfile · high confidence
Add colors example demonstrating NO\_COLOR support
A new example located in examples/colors demonstrates how to use color output functions in generated scripts. The example includes a sample application (colorly) that prints messages in various colors and explicitly supports the NO\_COLOR environment variable to disable color output. It also provides the necessary source files (bashly.yml, root\_command.sh, lib/colors.sh) and a test script to verify the behavior.
examples/colors · high confidence
Add colors-usage example demonstrating colored CLI output
This location introduces a new example project that demonstrates how to apply colors to various usage elements in a Bashly-generated CLI. It includes a \settings.yml\ configuration mapping usage components (such as commands, arguments, flags, and environment variables) to specific color functions, alongside a \src/lib/colors.sh\ library providing standard color utilities (e.g., green, bold, magenta) that respect the \NO\_COLOR\ environment variable. The example also provides the source configuration (\src/bashly.yml\) and command stubs to show how this feature is integrated into a generated script.
examples/colors-usage · high confidence
Add command-aliases example demonstrating single and multiple command aliases
This location introduces a new example that demonstrates how to define command aliases in a Bashly-generated CLI. The example includes a \bashly.yml\ configuration where the \download\ command is aliased to \d\, and the \upload\ command is aliased to both \u\ and \push\. It provides the corresponding shell script implementations and a test script to verify that the CLI correctly recognizes and executes these aliases alongside the primary command names.
examples/command-aliases · high confidence
Add command-groups example demonstrating command caption grouping
Added a new example in the \examples/command-groups\ directory that demonstrates how to visually group commands under custom captions (e.g., 'File Commands', 'Login Commands') in the generated help output. The example includes a \bashly.yml\ configuration defining an FTP-like CLI with grouped commands, along with the corresponding generated shell scripts, a README explaining the usage, and a test script to verify the output.
examples/command-groups · high confidence
Add command-paths example for nested command directories
Adds a new example demonstrating how to configure Bashly to place command files in nested sub-directories (e.g., \src/commands/\) via the \commands\_dir\ setting in \settings.yml\. The example includes a Docker-themed CLI structure with grouped commands (container, image, ps) and shows how the generated script organizes these into separate files while maintaining global options like \--debug\.
examples/command-paths · high confidence
Add commands example with sub-command support and environment variables
The examples/commands directory now includes a complete sample application demonstrating how to build a CLI script that supports sub-commands (download, upload), flags, arguments, and environment variables. This example showcases the generated script structure, including help output, version display, and command-specific help, along with the underlying bashly configuration and implementation files.
examples/commands · high confidence
Add commands-expose example demonstrating subcommand visibility control
This location introduces the \commands-expose\ example, which demonstrates how to control the visibility of subcommand summaries in help output. The example uses a \bashly.yml\ configuration to show that setting \expose: true\ displays subcommand summaries only when the parent command's help is requested (e.g., \cli config --help\), while \expose: always\ displays them even when running the parent command without arguments (e.g., \cli\). It also illustrates grouping subcommands under a custom header using the \group\ attribute.
examples/commands-expose · high confidence
Add configly example application with set, get, del, and list commands
The examples/config/src directory now includes a complete sample application called 'configly' that demonstrates how to use the config library. It provides four commands: 'set' to store key-value pairs, 'get' to retrieve values (with optional default values and variable assignment), 'del' to remove keys, and 'list' to display all configuration values or iterate through keys. The implementation uses the standard library functions from lib/config.sh, including config\_set, config\_get, config\_del, config\_has\_key, config\_keys, and config\_show.
examples/config/src · high confidence
Add custom-includes example for organizing code in additional functions
A new example located at examples/custom-includes demonstrates how to organize code by placing custom functions in a lib folder. The example includes a bashly.yml configuration, a root\_command.sh that calls a sample function, and a sample\_function.sh containing the custom logic, along with a test script to verify generation and execution.
examples/custom-includes · high confidence
Add default command example for Bashly
This location introduces a new example demonstrating how to configure a default command in Bashly. The example defines an \ftp\ CLI where the \upload\ command is marked as default, allowing it to run when no subcommand is specified (e.g., \ftp file\ executes \upload\). It includes the source YAML configuration, generated shell scripts for upload and download commands, a test script to verify behavior, and a README documenting the usage and output.
examples/command-default · high confidence
Add example demonstrating command examples on error
Added a new example project that shows how to configure the CLI to display usage examples when a user omits required arguments. The example uses a \settings.yml\ file with \show\_examples\_on\_error: true\ and defines command-specific examples in \bashly.yml\ for 'download' and 'upload' commands, ensuring that helpful context is provided during error states.
examples/command-examples-on-error · high confidence
Add example demonstrating conflicting flags
A new example in the examples/conflicts directory demonstrates how to define and use conflicting flags (e.g., --cache, --no-cache, --fast) that cannot be used together. The example includes a bashly.yml configuration, a generated download script, and a test script to verify the behavior, including error handling when conflicting flags are provided simultaneously.
examples/conflicts · high confidence
Add example demonstrating end-of-options delimiter usage
Added a new example in the \examples/end-of-options-delimiter\ directory that demonstrates how the \--\ delimiter allows values starting with \-\ to be parsed as positional arguments rather than flags. The example includes a \bashly.yml\ configuration for a \download\ command, a custom \root\_command.sh\ script, and a \test.sh\ script to verify the behavior.
examples/end-of-options-delimiter · high confidence
Add example demonstrating needy flags
Added a new example in the examples/needs directory that demonstrates the use of 'needy flags' in bashly, where certain flags require other specific flags to be present. The example includes a bashly.yml configuration defining flags with mutual dependencies (--add, --command, and --target), a generated CLI script, and a test script to verify the behavior.
examples/needs · high confidence
Add example for custom command function names
Added a new example demonstrating how to use the \function\ directive in \bashly.yml\ to override internal function names. This allows users to disambiguate commands that would otherwise generate identical function names, such as \cli container-start\ and \cli container start\, by assigning a unique base name like \deprecated\_container\_start\ to the hyphenated command.
examples/command-function · high confidence
Add example for forced default command behavior
This location introduces a new example demonstrating how to configure a command as the default using the \default: force\ option in the \bashly.yml\ configuration. The example includes the configuration file, generated shell scripts for the 'all' and 'only' commands, and a test script to verify that the forced default command executes when no arguments are provided or when the command line is unrecognized, replacing the standard usage text.
examples/command-default-force · high confidence
Add example for help header override
Added a new example in the \examples/help-header-override\ directory that demonstrates how to fully replace the help output header using the \help\_header\_override\ configuration in \bashly.yml\. The example includes a sample \download\ script with ASCII art in the header, along with the necessary source files, README, and test script to show the feature in action.
(repo-wide) · high confidence
Add example for private commands
Added a new example demonstrating how to define and use private commands that are hidden from the main help output but remain executable. The example includes a \bashly.yml\ configuration with \private: true\ flags for specific subcommands, along with the generated shell scripts and a test suite to verify the behavior.
examples/command-private · high confidence
Add extensible CLI example demonstrating external command extensions
Added a new example in the \examples/extensible\ directory that demonstrates how to configure a Bashly-generated CLI to accept external commands. The example includes a \bashly.yml\ configuration with the \extensible: true\ flag, source files for built-in commands (\upload\ and \download\), and a sample external executable (\cli-status\) that is invoked when an unrecognized command is passed to the CLI. A test script is also included to verify the generation and execution of this extensible behavior.
examples/extensible · high confidence
Add extensible-delegate example demonstrating unknown command delegation
This change introduces a new example in the \examples/extensible-delegate\ directory that demonstrates how to configure an external delegate command. By setting the \extensible\ property in \bashly.yml\ to \git\, the example shows how unknown commands (like \mygit status\) are automatically forwarded to the specified executable, while defined commands (like \push\ and \pull\) are handled locally. The entry includes the configuration file, generated shell scripts for local commands, and a test script to verify the delegation behavior.
examples/extensible-delegate · high confidence
Add footer example demonstrating custom help text
Added a new example in the \examples/footer\ directory that demonstrates how to configure and display a custom footer in the \--help\ output. The example includes a \bashly.yml\ configuration defining a multi-line footer, the generated shell script, and a test script to verify the output.
examples/footer · high confidence
Add help-command example demonstrating custom help subcommand
This location introduces a new example for the Bashly CLI generator that demonstrates how to implement a custom \help\ subcommand (e.g., \cli help download\) in addition to the standard \--help\ flag. The change adds the necessary source files (\src/bashly.yml\, \src/help\_command.sh\, etc.) and a test script to show users how to extend their CLI's help capabilities using the \bashly add help\ command.
examples/help-command · high confidence
Add hooks library with initialize, before, and after execution points
Users can now extend command execution by adding hook scripts via the \bashly add hooks\ command. This introduces three new library files—\initialize.sh\, \before.sh\, and \after.sh\—which allow users to inject custom logic at specific stages: \initialize\ runs before any processing (exposing raw \command\_line\_args\ for potential input override), \before\ runs after argument processing (exposing processed \args\ and \extra\_args\), and \after\ runs once a command completes. Each file contains a default echo statement and comments explaining the available variables and execution context.
lib/bashly/libraries/hooks · high confidence
Add internal-run example demonstrating command chaining
Added a new example in \examples/internal-run\ that demonstrates how to use the \run\ function to call CLI commands internally, enabling command chaining and logic reuse. The example includes a \bashly.yml\ configuration defining \build\, \test\, and \deploy\ commands, along with generated shell scripts showing how to capture arguments and invoke sub-commands (e.g., \run build production\) from within a parent command.
examples/internal-run · high confidence
Add key-value pair parsing example
Added a new example in the examples/key-value-pairs directory that demonstrates how to parse key=value pairs from both positional arguments and repeatable flags (e.g., --option key=value). The example includes a bashly configuration, a helper script to extract parameters into an associative array, and a root command script to display the parsed values.
examples/key-value-pairs · high confidence
Add markdown rendering library
Users can now generate Markdown documentation for their CLI scripts using the new \bashly add render\_markdown\ library. This adds a render script and a GTX template that produce an \index.md\ for the main command and separate Markdown files for each subcommand, including details on usage, examples, dependencies, environment variables, arguments, and flags (including \needs\ and \conflicts\). The library also supports a custom \x\_markdown\_footer\ definition in \bashly.yml\ to append additional content, and integrates with the \--show\ flag to preview the generated output.
lib/bashly/libraries/render/markdown · high confidence
Add multiline example demonstrating wrapped help text
The examples/multiline directory now includes a generated example project that demonstrates how Bashly handles multiline help messages for commands, arguments, flags, examples, and environment variables. The example shows that long help text is properly word-wrapped at the 80-character mark in the generated help output, and includes a .gitignore file to exclude generated artifacts.
examples/multiline · high confidence
Add nested command example with subcommand aliases and error handling
The \examples/commands-nested\ directory now provides a complete example demonstrating how to define nested commands (e.g., \cli dir list\, \cli file edit\) using \bashly.yml\. This example showcases the use of command aliases (such as \d\ for \dir\ and \f\ for \file\), argument reuse via YAML anchors, and the generation of specific shell scripts for each subcommand. It also illustrates the expected behavior for invalid commands, which now display an error message instead of usage help, and includes a test script to verify the generated CLI's functionality.
examples/commands-nested · high confidence
Add private-reveal example demonstrating hidden CLI elements
Added a new example in the examples/private-reveal directory that demonstrates how to hide private commands, flags, and environment variables from usage help text until a specific environment variable (SHOW\_PLEASE) is set. The example includes configuration files (bashly.yml, settings.yml), generated shell scripts, and a test script to verify the behavior.
examples/private-reveal · high confidence
Add render-mandoc example for man page generation
The examples/render-mandoc directory now includes a complete example demonstrating how to generate man pages using the mandoc renderer. It provides a sample bashly.yml configuration showing custom properties like x\_mandoc\_authors, x\_mandoc\_footer, and x\_mandoc\_see\_also, along with a README explaining the setup and a test script to render the documentation.
examples/render-mandoc · high confidence
Add repeatable argument example with unique and default support
The \examples/repeatable-arg\ directory now includes a complete demonstration of repeatable arguments, showing how to define an argument that accepts multiple values (e.g., \upcase file1 file2\). This example highlights three key capabilities: setting \repeatable: true\ to allow multiple inputs, using \unique: true\ to automatically filter out duplicate values, and specifying default values as an array (e.g., \file1\, \file2\). The included \src/root\_command.sh\ and \test.sh\ illustrate the runtime behavior, including how the space-delimited string is converted to an array and how duplicates are handled.
examples/repeatable-arg · high confidence
Add reusable-flags example demonstrating YAML anchor usage
A new example located at examples/reusable-flags demonstrates how to use YAML anchors to define flags once and reuse them across multiple commands. The example includes a bashly.yml configuration for 'download' and 'upload' commands, generated shell scripts, and a test script to verify the behavior.
examples/reusable-flags · high confidence
Add settings example demonstrating settings.yml configuration
The examples/settings directory now includes a complete example showing how to use a settings.yml file to configure script generation, such as setting the target output directory and enabling strict mode. This addition provides users with a reference implementation for managing CLI generation settings via YAML configuration alongside the standard bashly.yml.
examples/settings · high confidence
Add stacktrace standard library for error debugging
A new \stacktrace\ standard library is available to help debug script errors. By calling \enable\_stacktrace\ in your \src/initialize.sh\, the script will automatically print a detailed stack trace to stderr upon any error, including the file, line number, and function name for each frame, before exiting with the original error code.
lib/bashly/libraries/stacktrace · high confidence
Add standard help library for dynamic command assistance
Introduces a new standard library that provides a reusable 'help' command for generated bash scripts. This library allows users to view global help or specific command help by passing a command name as an argument, dynamically invoking the corresponding usage function if it exists, or displaying a 'No help available' message otherwise.
lib/bashly/libraries/help · high confidence
Add validations example demonstrating argument, flag, and environment variable checks
The \examples/validations/src\ directory now includes a sample Bashly application (\bashly.yml\) and its command implementation files (\calc\_command.sh\, \build\_command.sh\, \deploy\_command.sh\) that demonstrate how to apply validation rules. The example shows validating arguments as integers or non-empty, checking that file paths exist for flags, and ensuring environment variables point to existing directories, providing a reference for users implementing similar input validation in their own scripts.
examples/validations/src · high confidence
Add validations example demonstrating argument, flag, and environment variable validation
The examples/validations directory now includes a complete example showing how to use the \bashly add validations\ command to enable validation functions for arguments, flags, and environment variables. The example demonstrates built-in validators like \integer\, \not\_empty\, \file\_exists\, and \dir\_exists\, and shows how to apply them via the \validate\ key in \bashly.yml\, including array syntax for multiple validators. It also includes a test script that verifies the validation behavior.
examples/validations · high confidence
Add variables example demonstrating global and command-scoped definitions
Added a new example in the examples/variables directory that demonstrates how to define variables in the bashly.yml configuration. The example shows how to set global variables (like build\_number and environments) that are available across all commands, as well as command-specific variables (like output\_folder and download\_sources for the download command, and zip\_options for the compress command). It includes the configuration file, generated command scripts, and a test script to verify the behavior.
examples/variables · high confidence
Added automated demo generation script
A new AutoHotkey script (demo-maker.ahk) has been added to the support/demo directory to automate the creation of a demo GIF. This script records a terminal session using asciinema, executes a series of bashly commands to generate and test a CLI tool, and converts the recording into a GIF. A corresponding .gitignore file has also been added to exclude the generated application binary and cast data from version control.
support/demo · high confidence
Added built-in validation functions for file, directory, integer, and non-empty checks
The validation library now includes four new built-in validation functions: \validate\_dir\_exists\ (checks if a path is an existing directory), \validate\_file\_exists\ (checks if a path is an existing file), \validate\_integer\ (validates that input matches an integer pattern), and \validate\_not\_empty\ (ensures input is not empty). These functions provide standard validation capabilities for shell scripts generated by the tool.
examples/validations/src/lib · high confidence
Added catch-all argument example
A new example demonstrating the \catch\_all\ feature has been added to the examples directory. This example shows how to configure a command to accept an arbitrary list of arguments after the standard options, including support for the double-dash (\--\) argument parsing terminator to pass remaining arguments through.
examples/catch-all · high confidence
Added color formatting functions to the Bashly standard library
The \examples/dependencies/src/lib/colors.sh\ file introduces a set of shell functions for formatting output with colors and styles. Users can now wrap text in functions like \red\, \green\, \bold\, or \underlined\ to produce colored terminal output. The library respects the \NO\_COLOR\ environment variable to disable colors when requested and provides an \enable\_auto\_colors\ function to automatically detect if the terminal supports color output.
examples/dependencies/src/lib · high confidence
Added edge Docker image and build instructions for testing unreleased Bashly versions
Users can now test unreleased versions of Bashly directly from the GitHub repository using a new Docker image. The change introduces a Dockerfile that builds the gem from a specified branch (defaulting to master), installs it, and sets up a volume for local app access. An op.conf file provides convenience commands to build and push the edge image, and a README documents the usage for both Docker and direct Ruby installation methods.
edge · high confidence
Added example for custom script headers
The repository now includes an example demonstrating how to replace the default script header by placing a \header.sh\ file in the \src\ folder. This example, generated via Bashly, shows a minimal application that injects custom logic at the top of the generated script, while noting that \initialize.sh\ is generally preferred for initialization code.
examples/custom-script-header · high confidence
Added markdown rendering example for bashly
The examples/render-markdown directory now includes a complete example demonstrating how to render markdown documentation from bashly commands. This includes a sample bashly.yml configuration with custom properties (x\_markdown\_footer, dependencies), arguments, and flags, along with the generated docs/index.md output and a test script to regenerate the documentation.
examples/render-markdown · high confidence
Added new usage examples for default values, minimal scripts, and flag overrides
The examples/minimal directory now includes three new sample projects: 'default-values' demonstrates setting default values for arguments and flags, 'minimal' provides a basic 'hello world' style script, and 'minus-v' shows how to override the default -v and -h shortcuts for custom flags. Each example includes the source YAML configuration, generated shell scripts, documentation, and test suites to illustrate these specific CLI behaviors.
examples/minimal · high confidence
Added validation library functions for directory, file, integer, and non-empty checks
The validation library in lib/bashly/libraries/validations now includes dedicated shell functions for common input checks: validate\_dir\_exists, validate\_file\_exists, validate\_integer, and validate\_not\_empty. These functions provide specific error messages when inputs fail their respective checks (e.g., 'must be an existing directory', 'must be an integer'), enabling more precise validation feedback for users of the bashly library.
lib/bashly/libraries/validations · high confidence
Added whitelist example for argument and flag validation
A new example located at examples/whitelist demonstrates how to restrict arguments and flags to a predefined set of allowed values using the \allowed\ configuration. The example includes a \bashly.yml\ definition for a \login\ command with whitelisted region, environment, user, and protocol options, along with generated scripts and a test suite that verifies both valid inputs and rejection of invalid values.
examples/whitelist · high confidence
Advanced catch-all example with extended syntax and end-of-options support
The catch-all-advanced example now demonstrates the extended catch\_all syntax, allowing users to define a label and help message for catch-all arguments (e.g., 'AWS Params') and to mark catch\_all as required. It also illustrates the use of the double-dash (--) delimiter to disable input normalization, ensuring that arguments starting with hyphens are passed through correctly to the catch-all handler.
examples/catch-all-advanced · high confidence
Bashly switches to GTX templates and adds native shell completions
The command view templates have been migrated from ERB to the GTX templating engine, introducing a comprehensive set of new views for structured argument parsing, validation, and usage generation. This change adds native shell completion support for both Bash and Zsh, allowing users to enable tab-completion for commands, flags, and arguments. Additionally, the generated scripts now support advanced features such as default commands, extensible subcommands, environment variable validation, and user-defined hooks (before/after), while maintaining backward compatibility with existing Bashly configurations.
lib/bashly/views/command · high confidence
Example demonstrating multiple library directories
Added a new example in \examples/multiple-lib-dirs\ that shows how to configure \extra\_lib\_dirs\ in \settings.yml\ to load bash functions from multiple locations (specifically \common\_lib\ and \cloud\_lib\) and merge them into the generated script.
examples/multiple-lib-dirs · high confidence
Initial project scaffolding and configuration
This change establishes the foundational configuration and documentation for the Bashly project. It introduces essential development and CI files, including a new \.rubocop.yml\ (configuring RuboCop with \rentacop\ and targeting Ruby 3.3), a \Dockerfile\ for the Bashly 2.0.0 gem, and a \runfile\ for developer tasks. It also adds standard repository metadata and guides such as \.codespellrc\, \.gitattributes\, \.gitignore\, \.envrc.example\, \CONTRIBUTING.md\, and \release.md\, while removing legacy CI configuration (\.travis.yml\) and an older \Runfile\.
(repo-wide) · high confidence
New CLI commands and refactored generation behavior
Bashly introduces several new top-level commands: \bashly add\ installs libraries and customizations from local or remote sources; \bashly completions\ displays shell completion scripts; \bashly doc\ provides searchable reference documentation; \bashly render\ generates documentation from templates with optional file watching; and \bashly validate\ checks configuration files, now supporting a \--verbose\ flag to show the compiled config. The existing \bashly generate\ command (also aliased as \build\) has been refactored to inherit from a new \Base\ command class, adding support for \--quiet\ output, \--upgrade\ to update library functions, \--wrap\ to generate sourcing-friendly output, and \--env\ to control development vs. production modes. Additionally, generated scripts are now automatically made executable, and the \bashly shell\ command provides an interactive environment for running bashly commands.
lib/bashly/commands · high confidence
New INI library for managing configuration files with sections and environment variable support
A new INI library has been added to the Bashly standard library, providing functions to load, save, and inspect INI configuration files. Users can now populate a global associative array named \ini\ by calling \ini\_load\ on a config file, access values using dot notation for sections (e.g., \${ini\[section.key\]}\), and persist changes back to disk using \ini\_save\. The library supports optional sections, comments, and automatically expands environment variables within INI values using \envsubst\.
lib/bashly/libraries/ini · high confidence
New bash completion support for the bashly CLI
Users can now enable tab-completion for the bashly command-line interface. This change introduces a new \bashly completions\ command (with \--install\ and \--uninstall\ flags) to manage the installation of the completion script, and provides the generated \bashly-completions.bash\ file in the \lib/bashly/completions\ directory. The completion logic, generated via the \completely\ tool from \completely.yaml\, supports all existing bashly subcommands (init, preview, validate, generate, add, doc, render, shell) and their specific options, including argument completion for libraries and documentation topics.
lib/bashly/completions · high confidence
New catch-all stdin example
Added a new example in \examples/catch-all-stdin\ demonstrating how to use the \catch\_all\ feature to process multiple files as arguments or read from stdin. The example includes a Bashly configuration (\src/bashly.yml\) defining a \--format\ flag and a catch-all \file\ argument, along with a generated script (\src/root\_command.sh\) that collects file contents or stdin input. Test and documentation files are also included to show usage patterns.
examples/catch-all-stdin · high confidence
New color library with TTY auto-detection and NO\_COLOR support
The Bashly standard library now includes a new \colors\ module (\lib/bashly/libraries/colors/colors.sh\) that provides shell functions for formatting output with colors (red, green, blue, etc.) and styles (bold, underlined, and combinations). The library respects the \NO\_COLOR\ environment variable to disable colored output when set, and includes an \enable\_auto\_colors\ function that automatically disables colors if the output is not a TTY, ensuring clean logs in non-interactive environments.
lib/bashly/libraries/colors · high confidence
New command-examples directory demonstrating example configuration formats
Added a new example project in examples/command-examples that illustrates how to define command examples in bashly. The example shows two approaches: using an array of one-liners for the 'download' command and using a multi-line string for the 'upload' command to provide more descriptive help text. The directory includes the source YAML configuration, generated shell scripts, a test script, and a README explaining the usage.
examples/command-examples · high confidence
New config example demonstrating INI file management
Added a new example application named 'configly' that demonstrates how to read, write, and delete values in INI configuration files using the bashly config library. The example includes a sample configuration file, a test script to verify functionality, and documentation showing usage for commands like 'set', 'get', 'del', and 'list'.
examples/config · high confidence
New custom-strings example demonstrating localized help and error messages
Added a new example in examples/custom-strings that shows how to customize bashly's help and error message text. The example includes a bashly.yml configuration for a 'download' command and a src/bashly-strings.yml file that overrides default strings (e.g., changing 'Usage' to '== Usage ==' and customizing error messages like 'Boom! a required argument is missing'). It also provides a test.sh script to verify the generated output.
examples/custom-strings · high confidence
New docker-like and git-like CLI examples
Added new example projects demonstrating deeply nested command structures and global flags (docker-like) as well as standard subcommand patterns with aliases (git-like). These examples include generated source files, configuration manifests, documentation, and test scripts to illustrate best practices for building complex CLI applications.
examples/docker-like · high confidence
New example demonstrating alternate dependency requirements
Added the \examples/dependencies-alt\ example, which shows how to configure a script to require at least one command from a list of alternatives (e.g., \curl\ or \wget\). The example includes a \bashly.yml\ definition for the \download\ command with specific dependency rules and custom error messages, along with a generated \cli\ script that populates a \deps\ associative array with the paths to the found dependencies. It also includes a \colors\ library for formatted output and a test script to verify the setup.
examples/dependencies-alt · high confidence
New example demonstrating custom command filenames
Added a new example in the \examples/command-filenames\ directory that shows how to specify custom filenames for individual command source files using the \filename\ property in \bashly.yml\. The example includes a configuration for \cli\ with nested commands (\dir list\, \dir remove\, \file show\, \file edit\) mapped to specific paths under \src/\ (e.g., \dir\_commands/list.sh\), along with the generated shell scripts and a test script to verify the output.
examples/command-filenames · high confidence
New example demonstrating dependency validation with custom error messages
Added a new example in the dependencies section that shows how to require specific commands (like git, curl) to be installed before a script runs. The example demonstrates that when dependencies are missing, the script halts with friendly error messages. It also illustrates how to define dependencies as a hash to provide custom installation instructions, including support for colored output using the colors library.
examples/dependencies · high confidence
New example demonstrating repeatable flags with unique and default value support
Added a new example in \examples/repeatable-flag\ that shows how to use repeatable flags in Bashly. The example includes a \--data\ flag that accepts multiple values, a \--path\ flag that supports default values and enforces uniqueness (ignoring duplicate arguments), and a \--verbose\ flag that counts repeated occurrences. It also provides the generated shell script logic for handling these repeatable arguments and includes tests to verify the behavior.
examples/repeatable-flag · high confidence
New filters example demonstrating pre-command validation and argument access
Added a new example in the \examples/filters\ directory that demonstrates how to use filters to run checks before a command executes, potentially halting execution if an error is printed. The example includes a \bashly.yml\ configuration for \container\ and \redis\ commands, a \filters.sh\ library showing how to implement filter functions (like checking if Docker is running), and notes that the \${args\[\]}\ array is now available within filter functions for accessing command arguments.
examples/filters · high confidence
New library system with standardized add commands
Bashly introduces a new library management system that replaces the previous implementation, allowing users to install reusable code snippets and templates via the \bashly add\ command. This system includes a base library class and a YAML index defining available libraries such as \colors\ (with auto-color support), \config\ and \ini\ for handling configuration files, \hooks\ for script lifecycle events, \stacktrace\ for error debugging, and various renderers for Markdown and man pages. Users can now easily extend their generated scripts with these standardized components, which are installed into the user's lib or source directories as defined in the library configurations.
lib/bashly/libraries · high confidence
New mandoc and GitHub Markdown renderers with custom metadata support
Added two new render libraries: \:mandoc\ for generating Unix man pages (via pandoc) and \:markdown\_github\ for GitHub-compatible markdown documentation. The mandoc renderer supports custom YAML definitions (\x\_mandoc\_footer\, \x\_mandoc\_authors\, \x\_mandoc\_see\_also\) to extend man page content, while the markdown\_github renderer provides a README-focused output with specific formatting for flags, arguments, and dependencies. Both renderers support the \--show\ flag to preview generated files and respect private visibility settings for subcommands.
lib/bashly/libraries/render/mandoc · high confidence
New runtime completions example for bash and zsh
Added a new example in the \examples/completions\ directory that demonstrates how to expose the generated \send\_completions\ function through an application command. The example includes configuration files (\settings.yml\, \src/bashly.yml\) to enable full completions and a shell script (\src/completions\_command.sh\) that calls \send\completions\ based on the selected shell (bash or zsh). It also provides a test script to verify the generated completion scripts and the \\\_complete\ endpoint behavior.
examples/completions · high confidence
New split-config example demonstrating modular command definitions
Added a new example in examples/split-config that shows how to separate bashly configuration into multiple files. The example demonstrates importing commands from external YAML files (download\_command.yml) and from shell script front matter (upload\_command.sh), as well as importing shared flag definitions (common\_flags.yml) to keep the main bashly.yml concise.
examples/split-config · high confidence
New stack trace example for error debugging
Added an example demonstrating how to display stack traces on errors using the \enable\_stacktrace\ hook. This includes the \src/lib/stacktrace.sh\ library that traps errors and prints call stacks, along with a sample application (\download\) and tests to verify the behavior.
examples/stacktrace · high confidence
Support for importing external YAML snippets in configuration
Users can now include external YAML files within their bashly configuration by using an 'import' keyword. The new ComposeRefinements module processes these imports by loading the specified files, pre-processing them with ERB, and merging their contents into the main configuration. This allows for modular configuration management, with graceful error handling for missing files or invalid YAML structures.
lib/bashly/refinements · high confidence
Behavioural changes
Argument handling templates migrated to GTX with repeatable and validation support
The argument view templates in lib/bashly/views/argument have been replaced from ERB to GTX format, introducing support for repeatable arguments and refined validation logic. The new case.gtx and case\_repeatable.gtx templates handle argument assignment, with the latter supporting array-based storage for repeatable flags/args and optional uniqueness checks. The validations.gtx template now iterates over validation functions for each value in repeatable arguments, ensuring proper error reporting to stderr. Additionally, the usage.gtx template now displays default values as comma-separated lists when they are arrays, improving clarity for users defining repeatable arguments.
lib/bashly/views/argument · high confidence
Bashly 2.0.0: Major CLI overhaul with new commands and validation
Bashly has been upgraded to version 2.0.0, introducing a significantly expanded CLI interface and stricter configuration validation. New commands include \validate\ to check configuration files before generation, \render\ to preview output, \add\ for managing libraries, \doc\ for terminal documentation, \completions\ for shell integration, and \shell\ for an interactive mode. The \generate\ command is now also accessible via the \build\ alias. The tool now enforces comprehensive validation on \bashly.yml\ configurations via \ConfigValidator\, checking arguments, flags, dependencies, and catch-all settings. Configuration loading has been enhanced to support ERB preprocessing and YAML imports. Additionally, the file watcher has been switched to the \watchly\ gem, and the library system now supports git-sourced libraries and custom handlers.
lib/bashly · high confidence
Config library now uses associative arrays for INI handling
The config library in lib/bashly/libraries/config has been rewritten to use an associative array (via the underlying ini library) instead of previous line-based parsing. This change enables more robust handling of INI sections and key-value pairs, allowing users to get, set, delete, and check keys reliably. The library now supports default values in config\_get and provides functions like config\_keys and config\_has\_key for easier configuration management.
lib/bashly/libraries/config · high confidence
Enhanced string sanitization and new file/YAML loading utilities
The library now includes safer YAML loading that supports ERB pre-processing and handles Ruby version differences for untrusted content, alongside a new File extension for deep directory creation and appending. String handling has been significantly expanded with methods to sanitize output for safe printing (escaping quotes, backticks, and percent signs), format text for Markdown and man pages, and apply color codes based on settings. Additional string utilities allow for converting names to hyphens or paths, wrapping text, removing private comments or front matter, and expanding spaces to tabs.
lib/bashly/extensions · high confidence
Environment variable validation and usage display now use GTX templates
The environment variable view templates have been migrated from ERB to GTX, introducing two new template files: \usage.gtx\ and \validations.gtx\. The \usage.gtx\ template now explicitly prints allowed values and default values in the help output when they are defined. The \validations.gtx\ template implements runtime validation logic for environment variables, checking if a variable is set and running defined validation functions, exiting with an error if validation fails. This change also fixes an issue where validation was previously running twice.
_lib/bashly/views/environment\variable · high confidence
Flag handling refactored to GTX templates with enhanced validation and completion
The flag view templates have been migrated from ERB to the GTX templating engine, introducing comprehensive support for repeatable and unique flag arguments, explicit conflict and dependency (needs) validation, and structured runtime shell completions. Users will see improved error reporting for conflicting or missing required flags, better handling of repeated flag values, and more robust command-line completion behavior.
lib/bashly/views/flag · high confidence
New support/runfile tooling for completions, schema validation, and static analysis
The \support/runfile\ directory now includes dedicated scripts to manage bashly's internal tooling: \completions.runfile\ generates and installs bash completions for bashly itself using the \completely\ library; \schema.runfile\ generates JSON schemas from YAML sources and validates examples, fixtures, and settings against them; \static.runfile\ runs shellcheck and shfmt on example scripts; and \examples.runfile\ regenerates example scripts and their README documentation. These changes improve the reliability and maintainability of the bashly CLI by automating validation and documentation updates.
support/runfile · high confidence
Refactor bin scripts and update error message formatting
The bin/console script, which previously launched an IRB session with Bashly, has been removed. The bin/bashly script has been updated to use the new runfile syntax and now displays a simplified error message format (changing the previous 'rib\`' prefix style) when exceptions occur, while also ensuring the file is executable.
bin · medium confidence
Refactor library autoloading to use \`requires\` and \`autoloads\`
The library's initialization logic has been refactored to replace direct \require\ statements with a new autoloading system using the \requires\ and \autoloads\ methods. This change restructures how core components (such as CLI, Config, Models, and Commands) are loaded, moving model classes into a \Script\ namespace and organizing command and library classes into dedicated modules. This improves load performance and code organization by deferring the loading of unused classes until they are accessed.
lib · high confidence
Refactored introspection logic into dedicated modules with private visibility support
The introspection logic for commands, arguments, flags, environment variables, and other script components has been extracted from the main Command class into separate, dedicated modules (e.g., Introspection::Arguments, Introspection::Flags). This refactoring introduces support for private visibility settings, allowing commands, flags, and environment variables to be hidden from help output and completions unless a specific reveal key is configured. Additionally, the change ensures that wildcard aliases are excluded from completion suggestions and that help for private subcommands is only exposed when explicitly allowed.
lib/bashly/script/introspection · high confidence
Refactored script model classes into the Bashly::Script namespace
The internal model classes for the generated bash script (Argument, Base, CatchAll, Command, Dependency, EnvironmentVariable, Flag, Formatter, Variable, and Wrapper) have been moved into the Bashly::Script module. This refactoring organizes the codebase by separating script-generation logic from other concerns, ensuring that these classes are now explicitly namespaced under Script rather than living in the global Bashly namespace.
lib/bashly/script · high confidence
Removal of legacy model classes (Argument, Base, Command, Flag)
The internal model classes \Argument\, \Base\, \Command\, and \Flag\ within \lib/bashly/models\ have been completely removed. This deletion eliminates the previous data structures and logic used to represent CLI arguments, flags, and command hierarchies, indicating a significant internal refactoring or migration to a new model architecture.
lib/bashly/models · high confidence
Support for custom dependency installation messages
The example application now demonstrates that command dependencies can be defined as a hash mapping commands to custom installation instructions. This allows users to provide specific, user-friendly guidance (such as using colored text or external links) for installing required tools like 'mini-docker' or 'docker', rather than just checking for their existence.
examples/dependencies/src · medium confidence
Switch template engine from ERB to GTX and add helper concerns
The library now uses GTX templates instead of ERB for rendering scripts, which changes the file extension from .erb to .gtx and requires the GTX gem. This update also introduces new helper modules in the concerns directory: AssetHelper for loading assets, IndentationHelper for managing heredoc-aware indentation, SettingsCompletions for validating completion shell configurations, and ValidationHelpers for common configuration assertions. The Renderable concern has been updated to support these changes, including new methods for loading user files and handling view markers.
lib/bashly/concerns · high confidence
Updated wrapper script generation to use GTX templates
The wrapper script generation logic has been refactored to use GTX templates instead of the previous ERB format. This change introduces a bash version check that exits with an error if the running bash version is older than 4.2, updates the generated header to reference the new documentation domain (bashly.dev), and modifies the wrapper structure to define a function that is executed via a fallback mechanism if not sourced.
lib/bashly/views/wrapper · high confidence
Test coverage
Added and expanded test coverage for Bashly core extensions and helpers; Added approval fixtures for LibrarySourceConfig validation errors; Added approval test for completions help output; Added approval tests for CLI examples; Added approval tests for ERB config processing and YAML extension; Added approval tests for YAML compose refinements and error handling; Added approval tests for command visibility introspection; Added approval tests for mandoc and markdown rendering outputs; Added approval tests for mandoc rendering scenarios; Added approval tests for the CLI render command; Added approval tests for the \bashly add\ command; Added approval tests for the formatter component; Added comprehensive test coverage for Script model components; Added integration tests for bashly completion scripts and rendering; Added regression tests for repeatable argument and flag validations; Added render script fixture for testing; Added test approvals for bashly generate command enhancements; Added test coverage for Script::Introspection modules; Added test coverage for configuration validation errors; Added test coverage for library rendering and base classes; Added test fixture for Bash 3 syntax compatibility; Added test fixture for argfile environment variable override; Added test fixture for built-in validation functions; Added test fixture for custom BASHLY\_LIB\_DIR; Added test fixture for custom initialize script extension; Added test fixture for custom library source upgrades; Added test fixture for custom settings paths; Added test fixture for default argument/flag validation; Added test fixture for empty and flag arguments; Added test fixture for environment variable initialization behavior; Added test fixture for environment variable ordering; Added test fixture for error handling without examples; Added test fixture for flag arguments starting with a dash; Added test fixture for flag conflicts in fixed-flag context; Added test fixture for flag notation normalization; Added test fixture for global flags; Added test fixture for heredoc block handling; Added test fixture for local variable leakage; Added test fixture for non-compact short flags; Added test fixture for optional whitelist arguments and flags; Added test fixture for partials extension setting; Added test fixture for private environment variables help output; Added test fixture for private flags; Added test fixture for repeatable args/flags with quotes; Added test fixture for repeatable flags with allowed values; Added test fixture for required args and flags ordering; Added test fixture for shell script formatting; Added test fixture for short command aliases; Added test fixture for short flag default and required behavior; Added test fixture for subcommand version handling; Added test fixtures for CLI completion logic; Added test fixtures for catch-all help display and exit code validation; Added test fixtures for catch-all help flag behavior; Added test fixtures for configured runtime completions; Added test fixtures for custom library sources; Added test fixtures for disabling flag argument normalization; Added test fixtures for the bashly upgrade command; Added test fixtures for workspace command import; Added tests for ComposeRefinements; Added tests for negatable argfile behavior; Expanded test coverage for CLI commands; Expanded test coverage for core Bashly components; Expanded test fixtures for CLI argument parsing and validation; Removed obsolete model specs for Argument, Command, and Flag; Updated CLI approval tests for new commands and help text; Updated CLI help approval snapshots; Updated CLI init command approval tests; Updated bash version requirement approval; Updated documentation approval specs for CLI doc command; Updated test approvals for generated bash wrapper scripts; Updated test infrastructure and documentation.
Dependencies
Upgrade dependencies and drop support for Ruby versions below 3.3
The project has updated its runtime dependencies, replacing \requires\ with version 1.1, \colsole\ with 1.0, \mister\_bin\ with 0.9.0, and introducing new dependencies \gtx\ (0.1.1), \tty-markdown\ (0.7.2), and \watchly\ (0.2.0). Development dependencies have been refactored to use \rspec\_approvals\ instead of \rspec\_fixtures\, and \runfile\/\runfile-tasks\ are now optional. Additionally, the minimum supported Ruby version has been raised to 3.3, dropping support for earlier versions, and the gemspec metadata has been updated to point to the new bashly.dev domain.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 64 → 66 (+2.1)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 75 → 75 (+0.0)
- Architecture 98 → 98 (+0.0)
- Maturity 58 → 62 (+4.4)
- Readiness 62 → 62 (+0.0)
- Security 70 → 70 (+0.0)
Resolved (5)
- Ambiguous naming for validation methods. validate() and validate?() likely perform the same or very similar validation logic, with the ? suffix potentially indicating a boolean return or a side-effect-free check, but the distinction is unclear from signatures alone.
- Overlapping retrieval methods for commands. commands(), deep_commands(), public_commands(), and visible_commands() all retrieve collections of commands but with different filtering/scoping logic. While distinct, the naming convention is inconsistent (some imply depth, some visibility, some access level) without a clear hierarchy or base method.
- Proliferation of filtered environment variable lists. Same pattern as flags and commands, leading to API bloat and potential confusion about which list to use.
- Proliferation of filtered flag lists. Similar to commands, there are multiple methods returning subsets of flags with unclear distinctions between 'public', 'visible', and 'default'.
- Redundant accessor methods for boolean settings. The class provides both a generic enabled?(feature) method and specific enable_<feature>() methods for each boolean setting. This duplicates intent and API surface.
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
bashly-framework/bashly was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 3cf4064103b934de28ec4c5131610d4207ada76c — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.