bashly.dev

Bashly can automatically generate two forms of documentation for the bash script it produces: Markdown documentation and man page documentation. Both are generated as part of the tool's output, so you don't write them by hand — they are derived from the same YAML configuration that defines your commands, subcommands, arguments, and flags.

Where the documentation comes from

Bashly's workflow is configuration-driven. You describe your tool in a YAML file (commands, subcommands, arguments, and flags), and Bashly uses that description to generate a single standalone bash script. Because the YAML already contains the structure of your CLI, Bashly can reuse it to produce documentation that matches the actual behavior of the generated script.

The relevant sequence, per the Bashly site:

1. You provide a YAML configuration file describing commands, subcommands, arguments, and flags.
2. bashly init creates an initial sample YAML file for you.
3. bashly generate produces the bash script that parses and validates user input, provides help messages, and runs your code for each command.

Documentation generation sits alongside this generation step — it is listed among the features Bashly is responsible for, together with script generation, usage texts, and help screens.

The two documentation formats

Both are described as auto-generated for your script. The site does not specify file names, output directories, or command-line flags for controlling documentation output, so check the generated output or the project's documentation for the exact paths in your version.

How this relates to the built-in help

Auto-generated documentation is distinct from the runtime help that Bashly builds into the script itself. The generated script includes:

• Usage texts and help screens showing your tool's arguments, flags, and commands — including subcommands.
• Standard flags such as --help and --version.

So a user running your tool with --help sees help generated from the same configuration, while the Markdown and man page files serve as external reference material. All three stay consistent because they share one source: the YAML definition.

Practical implications

• Single source of truth. Because documentation is generated from the YAML config, updating a command or flag in the config and regenerating keeps docs in sync — provided you regenerate rather than hand-edit the output.
• No separate doc-writing step. You focus on your command code (kept in separate files per command and merged into the final script); Bashly handles usage texts, help screens, and documentation.
• Consistent with script quality. Bashly states the generated script is human-readable and compliant with shellcheck and shfmt; the documentation is generated from the same structured definition.

What the site does not specify

The available material does not describe:

• The exact filenames or locations of the generated Markdown and man page files.
• Any configuration options to customize or disable documentation generation.
• Whether documentation is generated by default on every bashly generate run or requires a separate step.

For those details, consult the Bashly documentation or inspect the output of bashly generate in your project.

Bashly's optional standard library adds framework-style helpers to the bash script it generates, so you don't have to write common utilities yourself. According to the Bashly documentation, these optional functions include color output, config file management (INI format), YAML parsing, Bash completions, "and more." They are separate from Bashly's core job of parsing arguments, validating input, and generating help screens — you opt into them when your tool needs that extra behavior.

The documented optional functions

The documentation describes these as "additional (optional) framework-style, standard library functions," which means they are not part of the minimal generated script — they're available when your tool's requirements call for them.

How they fit into the Bashly workflow

Bashly works from a YAML configuration file that describes your commands, subcommands, arguments, and flags. bashly init creates a sample configuration, and bashly generate produces a single standalone bash script that parses and validates user input, shows help, and runs your code for each command. Your per-command code lives in separate files and is merged into the final script.

The optional standard library functions sit on top of that generated script. They're the kind of utility code you'd otherwise write by hand in every tool — color codes, INI parsing, YAML handling, completion registration — packaged so the generated script stays consistent and shellcheck- and shfmt-compliant.

Deciding whether to use them

• Use color output if your tool's output is read by humans at a terminal and you want consistent formatting without maintaining escape-code helpers.
• Use INI config management if your settings are simple key-value pairs and you want users to edit a plain file. If your configuration is more complex or nested, the YAML parsing function may fit better.
• Use YAML parsing when your tool consumes or produces YAML — for example, reading a manifest or writing structured results.
• Add Bash completions once your command and flag surface is stable enough that users would benefit from tab-completion.

Because the documentation lists these as optional and points to "and more" on the site, treat the table above as the documented starting set rather than a fixed inventory. Check Bashly's feature list for the current functions before committing to a design that depends on a specific helper.

Bashly is a command line application written in Ruby that generates feature-rich bash command line tools. The workflow is: you describe your tool's commands, subcommands, arguments, and flags in a YAML configuration file, then run bashly generate to produce a single standalone bash script that parses and validates user input, prints help messages, and runs your code for each command. This suits anyone who wants framework-style argument parsing and help screens without writing that logic by hand in bash.

Step 1: Create the initial YAML configuration

Run bashly init to create an initial sample YAML file. This gives you a working starting point that you then edit to match your own tool.

Step 2: Describe your tool in YAML

In the configuration file, define:

• Commands and subcommands — the structure of your tool.
• Positional arguments — optional or required.
• Option flags — optional or required, with or without flag arguments.

Bashly uses this description both to generate the parser and to generate usage texts and help screens, including for subcommands.

Step 3: Generate the script

Run bashly generate. Bashly produces a single, standalone bash script that:

• Parses the user's command line and extracts arguments, flags, commands, and standard flags like --help and --version.
• Prevents your script from running unless the command line is valid.
• Includes human-readable output that is shellcheck-compliant and shfmt-compliant.

Step 4: Keep command code in separate files

Your code for each command lives in its own separate file. Bashly provides a place to input the code for each function your tool performs and merges it back into the final script. If you change the generated script, your separate files can be merged again.

What Bashly handles for you

When this workflow fits

Choose Bashly if you want to focus on your tool's specific code rather than on argument parsing, usage texts, and error messages. The trade-off is that you maintain a YAML description alongside your command files, and you regenerate the script after configuration changes rather than editing the final script directly.

Bashly generates a single, standalone bash script that handles command-line parsing, validation, help output, and standard flags, while leaving your command-specific logic in separate files that it merges into the final script. This applies when you describe your CLI in a YAML configuration and run bashly generate; Bashly then produces the script and keeps your per-command code in its own files.

Command-line parsing and validation

Bashly parses the user's command line and extracts:

• Positional arguments — optional or required.
• Option flags — optional or required, with or without flag arguments.
• Commands and subcommands — including nested subcommands.
• Standard flags — such as --help and --version.

It also prevents your script from running unless the command line is valid, so invalid input is rejected before your code executes.

Help, usage, and documentation

Bashly generates usage texts and help screens that show your tool's arguments, flags, and commands, and this works for subcommands as well. It can additionally auto-generate markdown and man page documentation for your script.

Script quality

The generated script is:

• Standalone — a single bash script.
• Human readable.
• shellcheck-compliant.
• shfmt-compliant.

Where your code lives

Bashly provides a place to input your code for each function your tool performs and merges it back into the final script. Each command's code is kept in a separate file, and it can be merged again if you change it.

Optional framework-style helpers

Bashly also offers optional standard library functions, including:

• Color output.
• Config file management (INI format).
• YAML parsing.
• Bash completions.
• And more.

How the pieces fit together

The practical effect is that you focus on your specific code rather than on argument parsing, usage texts, error messages, and similar concerns that a framework would normally handle in another language.

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.