Quick Reference
Installation
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>
.
Creating a command
There are three types of commands: standard, scripted, and external.
- Standard commands let you code the command directly in Ruby
- Scripted commands provide you with a bash script, where all of the parsed information (params, options, args, and config) is shared
- External commands let you wrap 3rd party applications directly
Standard Commands
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.
Scripted Commands
To create a new scripted command called bar
, run:
rbcli script -n bar
You will then find two new files:
- The command declaration under
application/commands/bar.rb
- The script code under
application/commands/scripts/bar.sh
Edit the script to write your code.
External Commands
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.
Hooks
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
Storage
RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.
Local State
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]
.
Remote State
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]
.
Userspace Configuration Files
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.
Logging
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.
Automatic Update Check
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.
Remote Execution
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> ...
Development and Contributing
For more information about development and contributing, please see the Official Development Documentation
License
The gem is available as open source under the terms of the GPLv3.