User Configuration Files

RBCli provides built-in support for creating and managing userspace configuration files. It does this through two chains: the defaults chain and the user chain.

Defaults chain

The defaults chain allows you to specify sane defaults for your CLI tool throughout your code. This gives you the ability to declare configuration alongside the code, and allows RBCli to generate a user config automatically given your defaults. There are two ways to set them:

  • YAML Files
    • You can store your defaults in one or more YAML files and RBCli will import and combine them. Note that when generating the user config, RBCli will use the YAML text as-is, so comments are transferred as well. This allows you to write descriptions for the options directly in the file that the user can see.
    • This is good for tools with large or complex configuration that needs user documentation written inline
    • These YAML files should be placed in the userconf/ directory in your project and they will automatically be loaded
  • DSL Statements
    • In the DSL, you can specify options individually by providing a name, description, and default value
    • This is good for simpler configuration, as the descriptions provided are written out as comments in the generated user config
    • You can put global configuration options in config/userspace.rb
    • Command-specific confiugration can be placed in the command declarations in application/commands/*.rb

DSL statements appear in both of the above locations as the following:

config_default :name, description: '<description_help_text>', default: '<default_value>'

User chain

The user chain has two functions: generating and loading configuration from a YAML file on the end user’s machine.

Rbcli will determine the correct location to locate the user configuration based on two factors:

  1. The default location set in config/userspace.rb
  2. The location specified on the command line using the --config-file=<filename> option (overrides #1)

To configure the default location, edit config/userspace.rb:

config_userfile '~/.mytool', merge_defaults: true, required: false
  • path/to/config/file
    • Self explanatory. Recommended locations are a dotfile in the user’s home directory, or a file under /etc such as /etc/mytool/userconf.yaml
  • merge_defaults
    • If set to true, default settings override user settings. If set to false, default settings are not loaded at all and the user is required to have all values specified in their config.
  • required
    • If set to true the application will not run if the file does not exist. A message will be displayed to the user to run your application with the --generate-config option to generate the file given your specified defaults.

Users can generate configs by running yourclitool --generate-config. This will generate a config file at the tool’s default location specified in the DSL. This location can be overridden via the --config-file=<filename> option.