YAML Configuration Guide

bashme works by reading a YAML configuration file to generate a robust, interactive, and stylized Bash script. This document details every available option.

1. Root Structure (`Config`)

The YAML file starts with global parameters defining the general behavior of the generated script.

Property	Type	Required	Description
`destinationFile`	`string`	YES	The path/name of the `.sh` file to be created.
`requireSudo`	`bool`	No	If `true`, the generated script will immediately check if it is run as root (sudo) and stop if not.
`bashHeader`	`string`	No	The file header (Shebang). Default: `#!/bin/bash`
`instructions`	`list`	YES	The ordered list of steps (`step`) to execute.

*Minimal Example:*

destinationFile: "install.sh"
requireSudo: true
instructions: [] # List of steps

2. Templating System

bashme integrates a dynamic replacement engine. You can use variables defined in input anywhere else (messages, commands, conditions).

Syntax: {{ VARIABLE_NAME }}
Compilation: Transformed into ${VARIABLE_NAME} in the final Bash script.

Fields supporting templating:

input.prompt
action.command
action.message
action.software
action.when
action.else
action.fallback.message

3. Instructions (`step`)

Each element of the instructions list must contain a step key. A step can be either user input (input) or an action (action).

A. User Input (`input`)

Allows asking a question to the user and storing the answer.

Property	Type	Description
`type`	`string`	• `text`: Visible input. • `secret` or `password`: Masked input (stars or invisible).
`prompt`	`string`	The question displayed to the user.
`variable`	`string`	The Bash variable name (Convention: UPPERCASE) to store the answer.

Example:

- step:
  name: "DB Configuration"
  input:
    type: "password"
    prompt: "Password for user {{ DB_USER }}"
    variable: "DB_PASS"

B. Actions (`action`)

Defines an operation to execute. The behavior changes according to the type.

Property	Type	Description
`type`	`string`	`command`, `message`, or `software-check`.
`message`	`string`	Text displayed (Action description or simple message).
`when`	`string`	(Optional) Raw Bash condition. The action executes if the condition is true.
`else`	`string`	(Optional) Bash command to execute if `when` is false.
`fallback`	`object`	(Optional) Error handling (see section 4).

Type: `command`

Executes a shell command in the background with a loading indicator (spinner).

Logs: Output (stdout/stderr) is captured. In case of error, it is displayed to the user.

Specific	Description
`command`	The command line to execute.


- step:
  name: "Install Nginx"
  action:
    type: "command"
    message: "Installing web server"
    command: "apt-get install -y nginx"

Type: `software-check`

Silently checks for the presence of a binary via command -v.

Specific	Description
`software`	The name of the program to search for (e.g., git, docker).

Note: Generally used with fallback to stop the script if the software is missing.

- step:
  name: "Check Git"
  action:
    type: "software-check"
    software: "git"
    fallback:
        quit_on_fail: true
        message: "Git is not installed!"

Type: `message`

Simply displays informative text (in green).

- step:
  name: "End"
  action:
    type: "message"
    message: "Installation complete! Go to http://{{ DOMAIN }}"

4. Conditions and Flow Control

You can make your scripts intelligent using the when and else fields.

When: It is a pure Bash condition placed in an if.
Else: It is the else block of Bash.

Complex Example:

- step:
  name: "Create config"
  action:
    type: "command"
    message: "Generating configuration file"
    command: "cp config.sample config.ini"
    # Condition: If the file does NOT exist
    when: "! -f config.ini"
    # Else: Display a message
    else: "echo \"config.ini file already exists, skipping...\""

5. Error Handling (`fallback`)

Add a fallback block to an action to define what to do if it fails (exit code != 0).

Property	Type	Description
`message`	`string`	Custom error message (displayed in yellow).
`quit_on_fail`	`bool`	• `true`: Stops the script (`exit 1`). • `false`: Displays the error but continues.

Example:

- step:
  name: "Download"
  action:
    type: "command"
    message: "Downloading file"
    command: "wget http://invalid-url.com/file.zip"
    fallback:
        message: "Unable to download file."
        quit_on_fail: true

6. Complete Example

Here is a complete YAML file combining all features:

destinationFile: "setup_app.sh"
requireSudo: true
bashHeader: "#!/bin/bash"

instructions:
    # 1. Ask for a variable
    - step:
      name: "Project Name"
      input:
        type: "text"
        prompt: "Name of your project"
        variable: "PROJECT_NAME"

    # 2. Check a dependency
    - step:
      name: "Check Node.js"
      action:
        type: "software-check"
        software: "node"
        fallback:
            message: "Node.js is required but not found."
            quit_on_fail: true

    # 3. Conditional action with templating
    - step:
      name: "Create folder"
      action:
        type: "command"
        message: "Creating folder /var/www/{{ PROJECT_NAME }}"
        command: "mkdir -p /var/www/{{ PROJECT_NAME }}"
        when: "! -d /var/www/{{ PROJECT_NAME }}"

    # 4. Final message
    - step:
      name: "Conclusion"
      action:
        type: "message"
        message: "Project {{ PROJECT_NAME }} initialized successfully!"

YAML Configuration Guide

1. Root Structure (Config)

2. Templating System

3. Instructions (step)

A. User Input (input)

B. Actions (action)

Type: command

Type: software-check

Type: message