Quick Reference

spec.add_dependency 'rbcli', '~> 0.4'

gem install rbcli

rbcli gem mytool

rbcli portable mytool
rbcli portable -a mytool # Adds annotations

#!/usr/bin/env ruby
require 'rbcli'

Rbcli::Configurate.cli do
  appname 'mytool'
  version '0.1.0'
  helptext "Something to tell your users about your application in --help"
  opt :verbose, 'Verbose output'
end

Rbcli.command "mycmd" do
  default
  action do |opts, _params, _args, _config, _env|
    Rbcli.log.info "Verbose!" if opts[:verbose]
    Rbcli.log.info "Hello, world!"
  end
end

Rbcli.go!

$ mytool -v
Verbose!
Hello, world!

rbcli command mycmd

Rbcli.command "mycmd" do
  #default  # The default command runs when no others are called 
  description 'Example command'
  usage "[--param|--otherparam] name"
  helptext "Text to show in --help"
  # Fields: name, description, (short, type, default, required, multi, permitted, prompt)
  parameter :myparam, 'Another Parameter', type: :string, default: "Default value", short: 'p'
  action do |opts, params, args, config, env|
    Rbcli.log.info "Top-level CLI Options: " + opts.to_s
    Rbcli.log.info "Parameters:            " + params.to_s
    Rbcli.log.info "Arguments on the CLI:  " + args.to_s
    Rbcli.log.info "The config:            " + config.to_s
    Rbcli.log.info "Environment variables: " + env.to_s
  end
end

mytool mycmd (--myparam|-p)

rbcli command -s mycmd

Rbcli.command "mycmd" do
  description "example script command"
  # external_script vars: {}, path: "./test.sh"
  inline_script vars: { foo: 'bar!!!' }, inline: <<~INLINE 
    log "Top-level CLI Options: $(rbcli opts .)"
    log "Parameters: $(rbcli params .)"
    log "Arguments on the CLI: $(rbcli args .)"
    log "Config: $(rbcli config .)"
    log "Environment Variables: $(rbcli env .)"
    log "Custom Var from command: $(rbcli vars .foo)"
    log "Same variable, in environment: ${FOO}"
    log "Log levels can also be set", "warn"
  INLINE

Rbcli::Configurate.cli do
  appname File.basename($0)
  author `Your Name`      # Can also be an %w(array of names)
  email your@email.com
  version Tester::VERSION
  copyright_year 2024
  license 'None'
  helptext "This text shows up in `#{File.basename($0)} --help`"
  opt :verbose, "Twice or more enables very-verbose output", multi: true
end

Rbcli::Configurate.cli do
  opt :myopttion, 'Description', long: 'myoption', short: 'm',
      type: :string, required: false, multi: false, permitted: nil
end

Rbcli.command "mycmd" do
  action do |opts, _params, _args, _config, _env|
    Rbcli.log.info "Top-level CLI Options: " + opts.to_s
  end
end

Rbcli::Configurate.logger do
  logger target: :stdout, level: :info, format: :display
  format :foo, Proc.new { |severity, datetime, progname, msg| "Foo! " + msg }
end

# Rbcli.log.level "message", "module" -- The module is optional
Rbcli.log.debug "Example Debug Message (change your log level to see this!)", "MSGS"
Rbcli.log.info "Example Info Message", "MSGS"
Rbcli.log.warn "Example Warning Message", "MSGS"
Rbcli.log.error "Example Error Message", "MSGS"
Rbcli.log.fatal "Example Fatal Message", "MSGS"
Rbcli.log.unknown "Example Unknown Message", "MSGS"
Rbcli.log.target STDERR #
Rbcli.log.format :json  # Change settings mid-execution
Rbcli.log.level :debug  #

Rbcli::Configurate.config do
  ##### Config (Optional) #####
  # The built-in config will automatically pull in a config file to a hash and vice versa
  # It can either be used immutably (as user-defined configuration) and/or to store application state
  #
  # file location:             <string> or <array>            (Required) Provide either a specific config file location or a hierarchy to search
  #      type:                 (:yaml|:json|:ini|:toml|:null) (Optional) Select which backend/file format to use. If the file has an associated extension (i.e. '.yaml') then this can be omitted.
  #      schema_location:      <string>                       (Optional) The file location of a JSON Schema (https://json-schema.org). If provided, the config will automatically be validated. (default: nil)
  #      save_on_exit:         (true|false)                   (Optional) Save changes to the config file on exit (default: false)
  #      create_if_not_exists: (true|false)                   (Optional) Create the file using default values if it is not found on the system (default: false)
  #      suppress_errors:      (true|false)                   (Optional) If set to false, the application will halt on any errors in loading the config. If set to true, defaults will be provided (default: true)
  file location: ['./tester.yaml', '~/.tester.yaml', '/etc/tester.yaml'],
       type: :yaml, schema_location: nil, save_on_exit: false,
       create_if_not_exists: false, suppress_errors: true
  ##### Banner (Optional) #####
  # Define a banner to be placed at the top of the config file.
  # Note that the banner will only be written to backends that support comments (:yaml, :ini, and :toml).
  banner <<~BANNER
    This text appears at the top of the config file when using a backend that supports comments.
    Tell the user a bit about what they're doing here.
  BANNER
  ##### Defaults (Optional) #####
  # Set defaults for your config values.
  #
  # Defaults set here will be provided to your application if the values are missing in the config.
  # They will also be used to create new config files when the flag `create_if_not_exists` is set to true.
  defaults({ setting_one: true, setting_two: false })
end

Rbcli.command "mycmd" do
  action do |_opts, _params, _args, config, _env|
    Rbcli.log.info "Config: " + config.to_s
  end
end

Rbcli::Configurate.envvars do
  ##### Environment Variable Parsing (Optional) #####
  # The envvars module can pull in all environment variables with a given
  # prefix and organize them into a hash structure based on name.
  # It will also parse the string values and convert them to the proper type (Integer, Boolean, etc)
  # Any values set here will be treated as defaults and made available when a variable is missing
  #
  # For example, these two environment variables:
  #   TESTER_TERM_HEIGHT=40
  #   TESTER_TERM_WIDTH=120
  # Would be declared here as:
  #   prefix 'TESTER'
  #   envvar 'TERM_HEIGHT', 40
  #   envvar 'TERM_WIDTH', 120
  # And get loaded into the env hash as:
  #   { term: { height: 40, width: 120 } }
  #
  # If the prefix is unset or equal to nil, the environment variables specified here will
  # be loaded without one.
  prefix 'TESTER'
  envvar 'DEVELOPMENT', false
end

Rbcli.command "mycmd" do
  action do |_opts, _params, _args, _config, env|
    Rbcli.log.info "Environment Variables: " + env.to_s
  end
end

Rbcli::Configurate.hooks do
  ##### Hooks (Optional) #####
  # These hooks are scheduled on the Rbcli execution engine to run
  # Pre- and Post- the command specified. They are executed after
  # everything else has been initialized, so the runtime configuration
  # values are all made available, as they will appear to the command.
  #
  # These are good for parsing and/or applying transformations on the
  # configuration before passing them to the command, and for cleaning
  # up your environment afterwards.
  pre_execute do |opts, params, args, config, env|
    Rbcli.log.info "I'm about to run a command..."
  end

  post_execute do |opts, params, args, config, env|
    Rbcli.log.info "I'm done running the command!"
  end
end

Rbcli::Configurate.updatechecker do
  ##### Update Check (Optional) #####
  # The application can warn users when a new version is released
  # Checks can be done either by rubygems or by a Github repo
  # Private servers for Github (enterprise) are supported
  #
  # Setting force_update to true will halt execution until it is updated
  #
  # For Github, an access_token is required for private repos. See: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
  gem 'tester', force_update: false, message: 'Please run `gem update tester` to upgrade to the latest version.'
  github 'repo/name', access_token: nil, enterprise_hostname: nil, force_update: false, message: 'Please download the latest version from Github'
end