bashly-framework/bashly

Bashly is a Ruby-based tool that generates standalone Bash CLI applications from YAML configuration files. It supports complex command structures including nested subcommands, aliases, and argument validation, while providing built-in features for shell completions, documentation rendering, and extensible library management. The system handles argument parsing, flag conflicts, and environment variable checks to produce robust, self-contained shell scripts.

75 changes.

This period covers the development and release of Bashly 2.0, featuring a complete architectural overhaul including a new library system, GTX templating engine, and comprehensive configuration validation. The work involved migrating core components to a namespaced structure, replacing legacy ERB templates, and introducing new CLI commands for library management, documentation, and interactive shells. Extensive test coverage and example projects were added to support these new features and ensure backward compatibility with the updated runtime requirements.

61 changes.

This period focused on expanding the Bashly standard library with new utilities for INI configuration, color formatting, input validation, and lifecycle hooks. It also introduced comprehensive documentation rendering capabilities, supporting Markdown and man page generation, while adding extensive examples and test fixtures to cover these new features.

29 changes.

This period focused on enhancing the CLI generator's introspection capabilities, introducing private visibility for commands and flags, and adding a stacktrace debugging library. It also significantly expanded the example suite to demonstrate new features like command chaining, variable scoping, and advanced shell completions. Concurrently, extensive test coverage was added to validate argument parsing, formatting, and completion logic.

Introduces a new standard library (src/lib/ini.sh) for reading and writing INI files with optional sections, including support for environment variable substitution in values via envsubst. This is demonstrated by a new example application (configly) that provides commands to list, get, set, and delete configuration values stored in an INI file.

examples/ini · high confidence

A new INI library is introduced in 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 with \ini\_save\. The library supports optional sections, comments, and automatically expands environment variables within INI values using \envsubst\.

lib/bashly/libraries/ini · high confidence

A new example demonstrating how to read from standard input has been added to the examples directory. The example includes a bashly configuration and generated shell script that use the '-' argument to handle both file paths and piped input, along with a test script to verify the behavior.

examples/stdin · high confidence

A new example has been added to the examples/yaml directory that demonstrates how to use the Bashly standard library to read YAML files. This includes a sample application (yaml) with a root command script, a helper library (src/lib/yaml.sh) for parsing YAML into shell variables, and a test script to verify functionality. The example shows how to load a YAML file, apply a prefix to variable names, and retrieve specific variables.

examples/yaml · high confidence

The \examples/completions-advanced\ directory now provides a complete example demonstrating advanced runtime shell completions. It includes configuration files (\bashly.yml\, \settings.yml\) and shell scripts that enable static candidates, dynamic external command outputs, internal function-based suggestions, and file/directory path completion, along with a test script to verify the generated completion behavior.

examples/completions-advanced · high confidence

Introduces a new example demonstrating the \catch\_all\ feature, allowing commands to receive arbitrary arguments. The example includes a \bashly.yml\ configuration enabling \catch\_all\ on the root command, a \root\_command.sh\ script that inspects arguments, and a \test.sh\ script to verify behavior, including handling of the double-dash argument terminator.

examples/catch-all · high confidence

The \examples/dependencies/src/lib/colors.sh\ library now includes functions for colored and formatted text output, such as \red\, \green\, \bold\, and \underlined\. These functions respect the \NO\_COLOR\ environment variable and support an \enable\_auto\_colors\ helper for automatic TTY detection, allowing scripts to produce styled terminal output.

examples/dependencies/src/lib · high confidence

The colors library now includes functions for black and white text, expanding the available color options alongside existing colors and styles. It also supports the NO\_COLOR environment variable to disable colored output in compliance with the no-color.org standard, and provides an enable\_auto\_colors function to automatically detect interactive terminals.

examples/colors/src/lib · high confidence

The examples/colors directory now includes a complete sample application that demonstrates how to use color functions in generated scripts. The example shows how to apply colored output (green, red, blue bold text) and explicitly supports the NO\_COLOR environment variable to disable colors when set, providing users with a reference implementation for integrating terminal colors into their CLI tools.

examples/colors · high confidence

A new example located in examples/colors-usage demonstrates how to apply colors to various usage elements in a generated CLI. It includes a sample bashly.yml configuration, a settings.yml file that maps usage elements (such as commands, arguments, and flags) to specific color functions, and a src/lib/colors.sh library providing standard color utilities. The example also provides a test script to verify the generated output.

examples/colors-usage · high confidence

The examples/command-aliases location now includes a complete demonstration of defining and using command aliases. The example shows how to configure a YAML spec to map single-character (e.g., 'd') and multi-word (e.g., 'push') aliases to existing commands, and includes the generated shell scripts and tests that verify these aliases function correctly alongside the primary command names.

(repo-wide) · high confidence

This location introduces a new example that demonstrates how to specify custom filenames for individual command source files using the \filename\ property in \bashly.yml\. The example shows how commands like \cli dir list\ can be mapped to specific paths (e.g., \src/dir\_commands/list.sh\) relative to the \src\ directory, allowing for organized command structures with sub-directories. It includes the configuration, generated shell scripts, and a test script to verify the generation and execution of these custom-named commands.

examples/command-filenames · high confidence

The examples/command-groups directory now includes a sample Bashly project that demonstrates how to visually group commands under custom captions (e.g., 'File' and 'Login') in the help output. This addition provides users with a concrete reference for organizing scripts with many commands into logical sections, including the necessary configuration (bashly.yml), generated scripts, and a test script to verify the grouped help display.

examples/command-groups · high confidence

The examples/commands directory now includes a complete, generated CLI example demonstrating how to build a script that supports sub-commands (download, upload), flags, arguments, and environment variables. This entry adds the source configuration (bashly.yml), generated script files, and a test suite to validate the output, serving as a reference for users implementing similar command structures.

examples/commands · high confidence

This change introduces a new example application named 'configly' located in examples/config/src. It provides a command-line interface for managing configuration values, featuring commands to set, get, delete, and list configuration entries. The implementation relies on a standard library (lib/config.sh) for core operations, demonstrating usage patterns such as checking for key existence, assigning default values, and iterating through configuration keys.

examples/config/src · high confidence

This change 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 execute when no subcommand is explicitly provided (e.g., \ftp file\ runs \upload\). It includes the source YAML configuration, generated shell scripts for upload and download commands, and a test script to verify the behavior.

examples/command-default · high confidence

Added a new example in the examples/conflicts directory that demonstrates how to define and handle conflicting command-line flags using Bashly. The example includes a bashly.yml configuration where flags like --cache, --no-cache, and --fast are set to conflict with each other, a generated download script, and a test script to verify the behavior. This serves as a reference for users implementing mutual exclusivity between options.

examples/conflicts · high confidence

A new example in the dependencies section shows how to define command dependencies as key-value pairs to provide custom, user-friendly installation instructions. The example demonstrates that when a required command is missing, the generated script can display specific help text (such as gem install commands or URLs) instead of a generic error, and includes a test script to verify this behavior.

examples/dependencies · high confidence

The \examples/repeatable-flag\ directory now includes a complete sample application (\download\) that demonstrates how to use repeatable flags. This example shows how to configure flags to accept multiple values (e.g., \-d one -d two\), how to enforce uniqueness on repeated arguments using the \unique\ setting, and how to define default values for repeatable arguments. It also illustrates handling verbose flags that count occurrences (e.g., \-vvv\) and includes generated shell scripts and tests to verify the behavior.

examples/repeatable-flag · high confidence

Added a new example in the \examples/command-function\ directory that demonstrates 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 \container-start\ and \container start\, by assigning a custom base name like \deprecated\_container\_start\ to avoid conflicts.

examples/command-function · high confidence

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 on specific subcommands (\connect-ftp\, \connect-ssh\) and the corresponding generated shell scripts and tests to verify this behavior.

examples/command-private · high confidence

An example project has been added to demonstrate how to configure a CLI application to accept external commands. By setting the \extensible\ flag to \true\ in the \bashly.yml\ configuration, the application will look for and execute external scripts (e.g., \cli-status\) found in the system PATH when a user runs a command not defined in the core schema. The example includes the configuration file, generated CLI scripts, and a test suite to verify this behavior.

examples/extensible · high confidence

The examples/extensible-delegate directory now includes a complete sample application (mygit) that demonstrates how to configure an extensible command structure. This example shows how to delegate unknown commands to an external executable (git) while defining specific local commands like push and pull, including the necessary source files, configuration, and test script.

examples/extensible-delegate · high confidence

A new example located in the footer directory demonstrates how to configure and display a custom footer section in the command-line help output. The example includes a bashly configuration file defining a multi-line footer, a generated root command script, and a test script to verify that the footer text appears correctly at the end of the help message.

examples/footer · high confidence

A new example located at examples/help-header-override demonstrates how to fully replace the help header in generated CLI output using the \help\_header\_override\ configuration in \bashly.yml\. The example includes a sample application that displays ASCII art in the help text, along with the necessary source files (\bashly.yml\, \root\_command.sh\) and a test script to verify the generation and output.

examples/help-header-override · high confidence

A new example located in examples/hooks demonstrates how to run common code before or after executing any command using bashly. The example includes source files for before and after hooks, an initialization hook for overriding raw input, and a root command script, along with a test script to verify the functionality.

examples/hooks · high confidence

Users can now extend command execution by adding lifecycle hooks via the \bashly add hooks\ command, which generates \initialize.sh\, \before.sh\, and \after.sh\ files. The \initialize\ hook runs first and exposes raw command-line arguments in the \command\_line\_args\ array, allowing advanced users to modify or override input before processing. The \before\ hook executes after argument processing but before the main command, providing access to processed arguments via \args\ and \extra\_args\, as well as the raw input array \input\. The \after\ hook runs once any command completes. Each hook file contains a default placeholder function and comments explaining its purpose, and users can safely delete any hook file if it is not needed.

lib/bashly/libraries/hooks · high confidence

A new example in the \examples/internal-run\ directory demonstrates how to use the \run\ function to call CLI commands internally, allowing users to chain commands or reuse logic without duplicating code. 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

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

The examples/multiline directory now includes a complete example project that demonstrates how to use YAML multi-line strings (using the \|- marker) to define detailed, wrapped help messages for commands, arguments, flags, examples, and environment variables. This example serves as a reference for users wanting to create rich, multi-paragraph help output in their generated bash scripts.

examples/multiline · high confidence

Added a new example in the examples/needs directory that demonstrates the use of 'needy flags' (mutually dependent options) in a Bashly-generated CLI. The example shows how to configure flags like --add, --command, and --target so that they enforce specific relationships (e.g., --add requires --command and --target), including validation logic and help text output.

examples/needs · high confidence

The \examples/commands-nested\ directory now provides a complete example demonstrating how to define nested commands (e.g., \cli dir list\, \cli file show\) using \bashly.yml\. This example includes command aliases (e.g., \dir\ as \d\), argument reuse via YAML anchors, and specific flags like \--force\. It also illustrates the expected behavior for invalid commands, showing that unrecognized subcommands or commands result in an error message rather than usage help, and includes a test script to verify this behavior.

examples/commands-nested · high confidence

Added a new example in the examples/private-reveal directory that demonstrates how to hide private commands, flags, and environment variables from usage text until a specific environment variable (SHOW\_PLEASE) is set. The example includes configuration files (bashly.yml, settings.yml), generated shell scripts for admin commands, and a test script to verify the behavior.

examples/private-reveal · high confidence

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 how to use custom properties like x\_mandoc\_authors, x\_mandoc\_footer, and x\_mandoc\_see\_also to enrich the generated man page output, along with a test script to verify the rendering.

examples/render-mandoc · high confidence

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 a CLI with 'download' and 'upload' commands, where flags like --force and --debug are defined in 'download' and referenced in 'upload' alongside a unique --password flag. It also provides the generated shell scripts and a test script to verify the behavior.

examples/reusable-flags · high confidence

The examples/completions directory now includes a complete example demonstrating how to expose the generated \send\_completions\ function through an application command. This setup allows users to generate shell completion scripts for Bash and Zsh at runtime by configuring \completions: full\ in \settings.yml\ and invoking the command with \bashly generate\.

examples/completions · high confidence

The examples/stacktrace directory now includes a complete sample application that demonstrates how to display detailed stack traces when errors occur. This example uses the enable\_stacktrace function to trap errors and output file, line number, and function call information, helping users understand how to debug their Bashly-generated scripts.

examples/stacktrace · high confidence

A new \stacktrace\ standard library has been added to Bashly, providing an \enable\_stacktrace\ function that users can call in their \src/initialize.sh\ to automatically capture and print detailed stack traces on errors. This feature uses \trap\ and \caller\ to output file, line, and function information to stderr, and ensures the original exit code is preserved and passed through.

lib/bashly/libraries/stacktrace · high confidence

Introduces a new standard library that provides a reusable 'help' command for generated bash scripts. This library allows users to query help for specific subcommands or view global help by passing a command name argument, dynamically invoking the corresponding usage function if it exists, or displaying an error if no help is available for the requested subject.

lib/bashly/libraries/help · high confidence

The \examples/validations\ directory now includes a sample Bashly application (\bashly.yml\) and its command implementation files (\build\_command.sh\, \calc\_command.sh\, \deploy\_command.sh\) that demonstrate how to apply validations to CLI inputs. The example shows how to validate arguments (e.g., \integer\), flags (e.g., \file\_exists\), and environment variables (e.g., \dir\_exists\), including the use of array syntax for multiple validations on a single input.

examples/validations/src · high confidence

A new example in the examples/variables directory demonstrates how to define and use variables in bashly configurations. It 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). The example includes configuration files, generated shell scripts, and a test script to verify the behavior.

examples/variables · high confidence

The support/demo area now includes a new AutoHotkey script (demo-maker.ahk) that automates the creation of a demo GIF by simulating terminal commands to initialize and run a sample Bashly application, along with a .gitignore file to exclude the generated application directory and recording data from version control.

support/demo · high confidence

Users can now enable tab-completion for bashly commands and options by running \bashly completions\ and sourcing the output, or by using the new \bashly completions --install\ command. This change introduces the \lib/bashly/completions\ directory containing the generation templates (\completely.yaml.gtx\), the generated completion script (\bashly-completions.bash\), and the configuration file (\completely.yaml\) that defines the supported commands, flags, and argument completions.

lib/bashly/completions · high confidence

The validation library in \examples/validations/src/lib\ now includes four new built-in validation scripts: \validate\_dir\_exists\, \validate\_file\_exists\, \validate\_integer\, and \validate\_not\_empty\. These additions allow users to enforce that input arguments correspond to existing directories or files, are valid integers, or are not empty strings, expanding the available validation capabilities for command-line arguments.

examples/validations/src/lib · high confidence

A new example located at examples/custom-includes has been added to demonstrate how to organize code by placing custom functions in a lib folder. The example includes a bashly.yml configuration, a root command script that calls a sample function, and the corresponding library file, along with a test script to verify generation and execution.

examples/custom-includes · high confidence

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), argument and flag definitions, the generated docs/index.md output, and a test script to regenerate the documentation.

examples/render-markdown · high confidence

The validation library in lib/bashly/libraries/validations now includes dedicated shell scripts 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.

lib/bashly/libraries/validations · high confidence

A new example demonstrating how to restrict arguments and flags to a predefined set of allowed values has been added. The example includes a \bashly.yml\ configuration for a \login\ command that enforces whitelists on the \region\ and \environment\ arguments, as well as the \--user\ and \--protocol\ flags, along with corresponding test and documentation files.

examples/whitelist · high confidence

The catch-all-advanced example now demonstrates the extended catch\_all syntax, allowing users to define custom labels and help messages for catch-all arguments (e.g., 'AWS Params' for the download command) and to mark catch-all arguments as required (e.g., for the upload command). It also illustrates the use of the double-dash (--) operator to disable input normalization when passing arbitrary arguments that start with a hyphen, ensuring they are treated as positional parameters rather than flags.

examples/catch-all-advanced · high confidence

Bashly has been upgraded to version 2.0.0.rc2, introducing several new CLI commands including \validate\ for configuration checks, \render\ for generating scripts, \add\ for managing libraries, \doc\ for documentation, \completions\ for shell completion installation, and \shell\ for an interactive mode. The tool now features a new library system (\Library\, \LibrarySource\, \LibrarySourceConfig\) that supports custom handlers, git-sourced libraries, and auto-upgrades. Configuration loading has been enhanced with ERB preprocessing and YAML imports via the \Config\ class, and a new \ConfigValidator\ enforces strict validation on commands, arguments, flags, and settings. The file watcher has been switched to the \watchly\ gem, and the CLI now displays a help footer with documentation links.

lib/bashly · high confidence

Added a new example in examples/custom-script-header that shows how to replace the default script header by placing a header.sh file in the src folder. The example includes a bashly.yml configuration, a custom header script that exits early under specific conditions, and a test script to verify the behavior.

examples/custom-script-header · high confidence

Bashly introduces several new commands to extend its functionality. The \bashly add\ command allows users to install and manage libraries from local directories, GitHub, or other git sources, supporting features like listing available libraries and forcing overwrites. A new \bashly render\ command enables users to generate documentation (such as Markdown or man pages) using internal or custom template sources, with support for watching for changes. Additionally, \bashly doc\ provides an interactive way to search and view the bashly reference documentation directly in the terminal, while \bashly shell\ offers an interactive shell for running bashly commands. The \bashly validate\ command now includes a \--verbose\ option to display the compiled configuration before validation, aiding in debugging split configs.

lib/bashly/commands · high confidence

Added an example in \examples/argfile\ that shows how to use the \argfile\ command option to load flag defaults from a file (\.download\). The example includes a \bashly.yml\ configuration, a sample argfile with boolean flags, value flags, and repeatable unique flags, along with a test script and README to demonstrate that arguments from the file are applied as defaults and can be overridden or extended by command-line arguments.

examples/argfile · high confidence

An example demonstrating how to handle multiple file arguments and read from stdin when no files are provided has been added to the examples directory. This sample CLI application uses the \catch\_all\ feature to collect file paths, processes their contents, and falls back to reading from standard input if no arguments are given, while also supporting a \--format\ flag.

examples/catch-all-stdin · high confidence

A new color library has been added to the standard library, providing shell functions to format 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 compatibility with non-interactive environments.

lib/bashly/libraries/colors · high confidence

Added a new example project in examples/command-examples that illustrates how to define command examples in bashly. The example shows that the examples field can be provided as either an array of one-liners (used in the 'download' command) or as a multi-line string for richer formatting (used in the 'upload' command). The directory includes the source YAML configuration, generated shell scripts, a test script, and a README documenting the usage.

examples/command-examples · high confidence

Added a new example in the \examples/command-paths\ directory that demonstrates how to organize bashly-generated scripts into nested sub-directories using the \commands\_dir\ setting in \settings.yml\. The example includes a \bashly.yml\ configuration for a Docker-like CLI with grouped commands (container, image, ps), the corresponding generated shell scripts under \src/commands/\, and a test script to verify the output structure and help text.

examples/command-paths · high confidence

The \examples/config/src/lib\ directory now includes \config.sh\ and \ini.sh\, providing a standard library for managing INI configuration files in Bashly projects. The \ini.sh\ module handles low-level parsing and saving of INI files, including support for sections and environment variable substitution in values via \envsubst\. The \config.sh\ module builds on this to offer a higher-level API with functions like \config\_get\ (supporting default values), \config\_set\, \config\_del\, and \config\_keys\, allowing users to easily load, read, modify, and save configuration data using a global \CONFIG\_FILE\ variable.

examples/config/src/lib · high confidence

Added a new example application named 'configly' that demonstrates how to read, write, and delete values in INI configuration files using a custom library built on top of the low-level INI parser. The example includes commands to set, get, delete, and list configuration keys, along with a sample config.ini file and a test script to verify functionality.

examples/config · high confidence

Added a new example in examples/custom-strings that shows how to customize bashly's help and error message strings. The example includes a configuration file (src/bashly-strings.yml) where users can define custom text for usage captions, fixed flags, and error messages (e.g., 'Boom! a required argument is missing'), along with a generated script and tests to verify the output.

examples/custom-strings · high confidence

Added new example projects demonstrating how to build complex CLI tools using bashly. The docker-like example showcases deeply nested commands (e.g., \docker container run\) and global flags (e.g., \--debug\), while the git-like example illustrates sub-command structures with specific flags (e.g., \git commit -m\). Both examples include generated source files, README documentation, and test scripts to validate the command behavior.

examples/docker-like · high confidence

Users can now easily test unreleased versions of Bashly using a new Docker image. The \edge\ directory introduces a Dockerfile that builds the gem directly from a specified GitHub branch (defaulting to master), along with an \op.conf\ script to streamline building and pushing the image. A README provides instructions for using the pre-built image via an alias or building it locally, enabling developers to try features before official release.

edge · high confidence

Added the \examples/dependencies-alt\ directory, which provides a complete example of how to configure a Bashly-generated script to require at least one tool from a list of alternatives (e.g., \curl\ or \wget\). The example includes a \bashly.yml\ configuration defining these alternate dependencies with custom help messages, a \colors.sh\ library with added \black\ and \white\ color functions, and a test script to verify the generated behavior.

examples/dependencies-alt · high confidence

Added a new example in the examples/command-examples-on-error directory that shows how to configure Bashly to display usage examples when a user omits required arguments. The example includes a CLI definition with 'download' and 'upload' commands, a settings file enabling 'show\_examples\_on\_error', and a test script to verify the behavior.

examples/command-examples-on-error · high confidence

Added a new example in the \examples/commands-expose\ directory that demonstrates how to use the \expose\ configuration option to show subcommand summaries in the parent command's help text. The example includes a \bashly.yml\ configuration file, generated shell scripts for various commands (init, config, server, container), and a test script to verify the behavior, illustrating both \expose: true\ and \expose: always\ modes.

examples/commands-expose · high confidence

Added a new example in the \examples/command-default-force\ directory that illustrates how to configure a command as the default using the \default: force\ option in the Bashly YAML specification. This setup ensures the command runs automatically when the script is executed without arguments or with unrecognized commands, rather than displaying the standard usage text. The entry includes the source configuration (\src/bashly.yml\), the generated shell scripts (\src/all\_command.sh\, \src/only\_command.sh\), and a test script (\test.sh\) to verify the behavior.

examples/command-default-force · high confidence

Added three new example projects in the examples directory to demonstrate key CLI configuration patterns. The 'default-values' example shows how to assign default values to arguments and flags. The 'minimal' example provides a basic 'hello world' style setup with required arguments. The 'minus-v' example demonstrates how to override the default short flags for help (-h) and version (-v) by assigning them to custom user-defined flags.

examples/minimal · high confidence

Added a new example in \examples/filters\ that demonstrates how to use command filters to run validation checks before a command executes. The example shows how to define filters (like \docker\_running\ and \redis\_running\) in the \bashly.yml\ configuration and implement them in \src/lib/filters.sh\. It highlights that the \${args\[\]}\ array is now available within filter functions, allowing validation logic to inspect command arguments, and illustrates that if a filter prints an error string, the command execution is halted.

examples/filters · high confidence

Bashly introduces a new library management system that allows users to easily extend their generated scripts with pre-built functionality. Users can now install libraries such as colors, config, help, hooks, ini, render\_markdown, render\_mandoc, stacktrace, strings, validations, and yaml using the 'bashly add' command. This system provides a consistent way to add features like colorful output, INI file handling, help commands, stacktraces, and documentation rendering templates to projects.

lib/bashly/libraries · high confidence

Users can now generate man pages via the new \:mandoc\ renderer (using pandoc) and GitHub-compatible Markdown via the new \:markdown\_github\ renderer. The mandoc renderer supports custom \x\_mandoc\_footer\, \x\_mandoc\_authors\, and \x\_mandoc\_see\_also\ definitions, while both renderers now respect the \flag.needs\ constraint and filter out private commands from the output.

lib/bashly/libraries/render/mandoc · high confidence

Users can now generate Markdown documentation for their CLI scripts using the new \render/markdown\ library. By running \bashly render :markdown\, the tool creates an \index.md\ file for the main command and separate Markdown files for each subcommand, utilizing a new \markdown.gtx\ template. The generated documents include command usage, examples, dependencies, environment variables, arguments, and flags (including \needs\ and \conflicts\ attributes). A custom \x\_markdown\_footer\ definition allows adding extra content to the output, and the \--show\ flag enables previewing the rendered Markdown in the terminal.

lib/bashly/libraries/render/markdown · high confidence

The \examples/repeatable-arg\ directory now provides a complete demonstration of repeatable arguments, including support for the \unique\ flag to ignore duplicate values and the ability to define defaults as an array. The example generates a CLI tool that processes multiple files, showing how to handle space-delimited input and apply default values when no arguments are provided.

examples/repeatable-arg · high confidence

Added a new example in the \examples/settings\ directory that demonstrates how to use a \settings.yml\ file to configure script generation aspects, such as setting the output directory (\out\) and enabling strict mode. The example includes the necessary source files (\bashly.yml\, command stubs), the configuration file, and a test script to verify the generated CLI behavior.

examples/settings · high confidence

Added a new example in examples/split-config that shows how to separate bashly configuration into multiple files. The example demonstrates importing command definitions from external YAML files (src/download\_command.yml) and from YAML front matter within shell scripts (src/upload\_command.sh), as well as importing shared flag definitions (src/common\_flags.yml) to keep the main bashly.yml clean.

examples/split-config · high confidence

The \support/runfile\ directory now includes dedicated runfiles to manage development workflows: \completions.runfile\ generates and installs bash completions for bashly using the \completely\ library; \schema.runfile\ generates JSON schemas from YAML sources and validates examples and fixtures against them; \static.runfile\ runs shellcheck and shfmt on example scripts; \examples.runfile\ regenerates example scripts and documentation; and \example.rb\ provides helper classes for these tasks. These changes streamline the generation, validation, and maintenance of bashly's examples, completions, and configuration schemas.

support/runfile · high confidence

Added a new example in \examples/validations\ that demonstrates how to use the \bashly add validations\ command to enforce validation rules on arguments, flags, and environment variables. The example shows how to define validation functions (such as \integer\, \not\_empty\, \file\_exists\, and \dir\_exists\) in the \bashly.yml\ configuration and how the generated script handles validation errors for invalid inputs.

examples/validations · high confidence

Users can now include external YAML files in their bashly configuration by using an 'import' keyword. The new ComposeRefinements module recursively processes configuration hashes and arrays, loading referenced files via YAML.load\_erb\_file to allow ERB preprocessing. If an import file is missing or does not contain valid YAML, the system raises a clear ConfigurationError instead of failing silently or with a generic exception.

lib/bashly/refinements · high confidence

The \settings.yml\ configuration now supports an \extra\_lib\_dirs\ property, allowing users to specify multiple directories (e.g., \common\_lib\, \cloud\_lib\) to search for additional bash functions. When generating the script, bashly merges any bash scripts found in these specified directories (and their subdirectories) into the final output, enabling the use of functions from multiple distinct library sources within a single generated application.

examples/multiple-lib-dirs · high confidence

This change establishes the foundational configuration files for the Bashly project, including \.rubocop.yml\ (targeting Ruby 3.3 with \rentacop\ inheritance), \.codespellrc\, \.gitattributes\, and \.rubycritic.yml\. It introduces a new \runfile\ for developer tasks, replacing the legacy \Runfile\ and Travis CI configuration (\.travis.yml\) with a modern setup. Additionally, it adds example environment configuration (\.envrc.example\), a Dockerfile for the bashly gem, and updates \.gitignore\ and \.rspec\ to reflect the new project structure and tooling.

(repo-wide) · high confidence

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

The command view templates in lib/bashly/views/command have been migrated from ERB to the GTX templating format, introducing a comprehensive set of new, granular template files (such as argfile\_filter, catch\_all\_filter, command\_fallback, and various completion scripts) while removing the previous monolithic ERB files. This change restructures how generated bash scripts are assembled and executed: the entry point now uses a start() function that initializes the environment and then calls run(), replacing the previous direct initialize/run calls. It also introduces native runtime completion support for bash and zsh via dedicated completion\_script templates, adds support for command argfiles to inject arguments from files, and implements a command\_fallback mechanism to handle default commands, extensible commands, and invalid subcommands more robustly.

lib/bashly/views/command · high confidence

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

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

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

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

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

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

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

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

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

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

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

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

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 example behaviors; 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 markdown 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 default command with flags only; 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 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.

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 watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 66.

• Code Health 99
• Architecture 100
• Maturity 62
• Readiness 60
• Security 63

• 300 commits — 249 feature/other, 51 fixes

• lib/bashly — 77 commits
• (repo) — 75 commits
• (root) — 55 commits
• spec/approvals — 25 commits
• spec/bashly — 9 commits
• schemas/settings.json — 8 commits
• spec/fixtures — 8 commits
• .github/workflows — 7 commits
• examples/render-mandoc — 7 commits
• examples/argfile — 6 commits
• examples/stacktrace — 5 commits
• examples/internal-run — 4 commits
• schemas/bashly.json — 3 commits
• examples/command-line-manipulation — 2 commits
• examples/completions — 2 commits
• examples/config — 2 commits
• examples/multiple-lib-dirs — 2 commits
• examples/colors — 1 commit
• examples/help-header-override — 1 commit
• examples/validations — 1 commit

• fix: - Fix completions for a default command
• fix: - Fix filewatcher interrupt
• fix: - Fix function name in root command comment
• fix: - Fix local variables leaking from internal functions
• fix: - Fix premature exit in validate_not_empty validation function
• fix: - Fix quoted heredocs
• fix: - Fix render markdown command examples
• fix: - Fix validation running twice for environment variables
• fix: - Fix validations to only run once
• fix: - Revert 9167c49 to allow calling run ... internally
• fix: Merge branch 'master' into revert/9167c49
• fix: Merge pull request #603 from DannyBen/revert/9167c49
• fix: Merge pull request #610 from DannyBen/fix/no-color-spec
• fix: Merge pull request #634 from DannyBen/fix/validate_not_empty
• fix: Merge pull request #639 from DannyBen/fix/render-examples
• fix: Merge pull request #660 from bashly-framework/fix/root-function-name
• fix: Merge pull request #661 from bashly-framework/fix/env-var-validation
• fix: Merge pull request #662 from bashly-framework/fix/double-env-var-validation
• fix: Merge pull request #682 from bashly-framework/fix/local-var-leakage
• fix: Merge pull request #692 from bashly-framework/fix/watcher-interrupt
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

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.