Advanced Command Types

RBCli has three different command types:

• Standard Commands (Ruby-based)
• Scripted Commands (Ruby+Bash based)
• External Commands (Wrapping a 3rd party application)

This document is provided to be a reference. If you would like an in-depth tutorial, please see Your First Command.

General Command Structure

Commands in RBCli are created by subclassing Rbcli::Command. All commands share a certain common structure:

class List < Rbcli::Command                                                           # Declare a new command by subclassing Rbcli::Command
    description 'TODO: Description goes here'                                           # (Required) Short description for the global help
    usage <<-EOF
TODO: Usage text goes here
EOF                                                                                   # (Required) Long description for the command-specific help
    parameter :force, 'Force testing', type: :boolean, default: false, required: false  # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times

    config_default :myopt2, description: 'My Option #2', default: 'Default Value Here'  # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config.
                                                                                      # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options
end

• description
  • A short description of the command, which will appear in the top-level help (when the user runs mytool -h).
• usage
  • A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you'd like. It will show up as a long, multi-line description when the user runs the command-sepcific help (mytool list -h).
• parameter
  • Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on Options, Parameters, and Arguments
• config_default
  • This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on User Config Files

Standard Commands

Standard commands are written as ruby code. To create a standard command called list, run:

rbcli command --name=list
#or
rbcli command -n list

A standard command can be identified by the presence of an action block in the definition:

class List < Rbcli::Command
    action do |params, args, global_opts, config|
        # Code goes here
    end
end

Your application's parameters, arguments, options, and config are available in the variables passed into the block. For more information on these, see Options, Parameters, and Arguments.

Scripted Commands

Scripted commands are part Ruby, part Bash scripting. They are a good choice to use if you feel something might be easier or more performant to script with Bash, or if you already have a Bash script you'd like to use in your project. You can create one with:

rbcli script -n list

This will create two files in your RBCli project: a Ruby file with the common command declaration (see General Command Structure), and a bash script in the folder application/commands/scripts/.

You can tell a command is a script by the line:

class List < Rbcli::Command
    script
end

RBCli will pass along your applications config and CLI parameters through JSON environment variables. To make things easy, a Bash library is provided that makes retrieving and parsing these variables easy. It is already imported when you generate the command, with the line:

source $(echo $(cd "$(dirname $(gem which rbcli))/../lib-sh" && pwd)/lib-rbcli.sh)

This will find the library which is stored on the system as part of the RBCli gem.

You can then retrieve the values present in your variables like such:

rbcli params
rbcli args
rbcli global_opts
rbcli config
rbcli myvars

echo "Usage Examples:"
echo "Log Level:  $(rbcli config .logger.log_level)"
echo "Log Target: $(rbcli config .logger.log_target)"
echo "First Argument (if passed): $(rbcli args .[0])"

For your convenience, the script will have all the instructions needed there. For more instructions on how to use JQ syntax to parse values, see the JQ documentation.

External Commands

External Commands are used to wrap 3rd party applications. RBCli accomplishes this by allowing you to set environment variables and command line parameters based on your input variables.

RBCli provides this feature through the extern keyword. It provides two modes -- direct path and variable path -- which work similarly.

Direct Path Mode

Direct path mode is the simpler mode of the two External Command modes. It allows you to provide a specific command with environment variables set, though it does not allow using RBCli parameters, arguments, options, and config.

ruby class List < Rbcli::Command extern path: 'path/to/application', envvars: {MYVAR: 'some_value'} # (Required) Runs a given application, with optional environment variables, when the user runs the command. end

Here, we supply a string to run the command. We can optioanlly provide environment variables which will be set for the external application.

Variable Path Mode

Variable Path mode works the same as Direct Path Mode, only instead of providing a string we provide a block that returns a string (which will be the command executed). This allows us to generate different commands based on the CLI parameters that the user passed, or pass configuration as CLI parameters to the external application:

class Test < Rbcli::Command
    extern envvars: {MY_OTHER_VAR: 'another_value'} do |params, args, global_opts, config|          # Alternate usage. Supplying a block instead of a path allows us to modify the command based on the arguments and configuration supplied by the user. This allows passing config settings as command line arguments to external applications. The block must return a string, which is the command to be executed.
        cmd = '/path/to/application'
        cmd += ' --test-script foo --ignore-errors' if params[:force]
        cmd
    end
end

NOTE: Passing user-supplied data as part of the command string may be a security risk (example: /path/to/application --name #{params[:name]}). It is highly recommended to provide the fixed strings yourself, and only select which strings are used based on the variables provided. This is demonstrated in the example above.