What Is Bashly and What Does It Do?

Updated

Bashly is a command line application written in Ruby that generates feature-rich bash command line tools. You describe your tool's commands, subcommands, arguments, and flags in a YAML configuration file, and Bashly generates a single standalone bash script that parses and validates user input, prints help messages, and runs your code for each command. It is a good fit if you want a distributable bash CLI without hand-writing argument parsing, usage text, and error handling; it is not a runtime library your script depends on, since the output is a self-contained script.

How Bashly works

The workflow is configuration-first:

  1. Describe the tool in YAML. You provide a configuration file covering commands, subcommands, arguments, and flags.
  2. Initialize a sample. Running bashly init creates an initial sample YAML file for you.
  3. Generate the script. Running bashly generate produces the bash script that handles parsing, validation, help, and dispatch.
  4. Write your own code separately. The code for each command lives in its own file and can be merged back into the final script, so regenerating does not force you to rewrite your logic.

The key mechanism is separation of concerns: Bashly owns the command line framework layer, and you own the behavior of each command.

What Bashly handles for you

According to the project, Bashly is responsible for:

  • Generating a single, standalone bash script.
  • Producing a human-readable, shellcheck-compliant and shfmt-compliant script.
  • Generating usage texts and help screens showing arguments, flags, and commands, including subcommands.
  • Parsing the user's command line and extracting:
    • optional or required positional arguments
    • optional or required option flags, with or without flag arguments
    • commands and subcommands
    • standard flags such as --help and --version
  • Preventing the script from running unless the command line is valid.
  • Providing a place for your code for each function the tool performs, and merging it back into the final script.
  • Optional framework-style standard library functions, including color output, config file management (INI format), YAML parsing, and bash completions.
  • Auto-generating markdown and man page documentation for your script.

When Bashly is a good fit

Choose Bashly when you are building a bash CLI with multiple commands or subcommands and want consistent parsing, validation, and help output without writing that plumbing yourself. It also suits teams that want generated documentation and shell completions alongside the script.

Consider alternatives when your tool is a single trivial script with no arguments, or when you need a runtime framework rather than generated output—Bashly's value comes from generating a standalone script from a YAML definition, not from being linked into your code.

Getting started

A minimal path is: install Bashly, run bashly init to create the sample YAML, edit the YAML to match your commands and flags, run bashly generate, then fill in the per-command code files and regenerate to merge them. The generated script is the artifact you distribute.