RBCli is available on rubygems.org. You can add it to your application’s Gemfile or gemspec, or install it manually by running:
gem install rbcli
Then, cd to the folder you’d like to create your project under and run:
rbcli init -n mytool -d "A simple CLI tool"
Or, for a single-file tool without any folder/gem tructure, run rbcli init -t mini -n <projectname> or rbcli init -t micro -n <projectname>.
There are three types of commands: standard, scripted, and external.
To create a new command called foo, run:
rbcli command -n foo
You will now find the command code in application/commands/list.rb. Edit the action block to write your coode.
To create a new scripted command called bar, run:
rbcli script -n bar
You will then find two new files:
application/commands/bar.rbapplication/commands/scripts/bar.shEdit the script to write your code.
To create a new external command called baz, run:
rbcli extern -n baz
You will then find the command code in application/commands/baz.rb.
Use one of the two provided modes – direct path mode or variable path mode – to provide the path to the external program.
RBCli has several hooks that run at different points in the exectution chain. They can be created via the rbcli command line tool:
rbcli hook --default # Runs when no command is provided
rbcli hook --pre # Runs before any command
rbcli hook --post # Runs after any command
rbcli hook --firstrun # Runs the first time a user runs your application. Requires userspace config.
rbcli hook -dpof # Create all hooks at once
RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.
RBCli can provide you with a unique hash that can be persisted to disk on any change to a top-level value.
Enable local state in config/storage.rb.
Then access it in your Standard Commands with Rbcli.local_state[:yourkeyhere].
Similar to the Local State above, RBCli can provide you with a unique hash that can be persisted to a remote storage location.
Currently only AWS DynamoDB is supported, and credentials will be required for each user.
Enable remote state in config/storage.rb.
Then access it in your Standard Commands with Rbcli.remote_state[:yourkeyhere].
RBCli provides an easy mechanism to generate and read configuration files from your users. You set the default values and help text with the defaults chain, and leverage the user chain to read them.
You can set defaults either by placing a YAML file in the userconf/ folder or by specifying individual options in application/options.rb (global) or application/command/*.rb (command-specific).
Users can generate a config file, complete with help text, by running your tool with the --generate-config option.
RBCli’s logger is configured in config/logging.rb.
log_level :info
log_target 'stderr'
Then it can be accessed when writing your commands via:
Rbcli::log.info { 'These logs can go to STDERR, STDOUT, or a file' }
The user will also be able to change the log level and target via their config file, if it is enabled.
RBCli can automatically notify users when an update is available. Two sources are currently supported: Github (including Enterprise) and RubyGems.
You can configure automatic updates in config/autoupdate.rb in your project.
RBCli can automatically execute script and extern commands on remote machines via SSH. Enable this feature in config/general.rb by changing the following line to true:
remote_execution permitted: false
Then for each command you want to enable remote execution for, add the following directive:
remote_permitted
Users can then execute commands remotly by specifying the connection string and credentials on the command line:
mytool --remote-exec [user@]host[:port] --identity (/path/to/private/ssh/key or password) <command> ...
For more information about development and contributing, please see the Official Development Documentation
The gem is available as open source under the terms of the GPLv3.