Consoler Build Status Gem Version

Sinatra-like application builder for the console

Quick usage

```ruby # create an application app = description: ‘A simple app’

define a command ‘[–clean] output_dir’ do |clean, output_dir| # clean contains a boolean clean_up if clean

# output_dir contains a string build_project output_dir end[‘build’, ‘production’, ‘–clean’])

this does not match, nothing is executed and the usage message is printed[‘deploy’, ‘production’])

defaults to ARGV ```


  • No fiddling with ARGV and friends
  • Arguments filled based on their name, for easy access
  • Grouped optionals


Tests are run against multiple ruby versions (latest supported):

  • 2.2.x
  • 2.3.x
  • 2.4.x
  • 2.5.x

No other requirements exist.


sh gem install consoler

or add to your Gemfile for applications

ruby gem 'consoler', '~> 1.0.3'

or to your .gemspec file for gems

ruby do |spec| spec.add_dependency 'consoler', '~> 1.0.3' end


Full API documentation can the found here:


Creating an application

```ruby # create an application app =

.. or with a description that will show up in the usage message

app = description: ‘A simple app’ ```

Adding commands

All actions you want to create must have a command name, there is no top-level matching available at this point.

```ruby # create an application app =

in the most simple way, you provide a name (the method name) and a block you

# want to execute if it matches do # your code here end

to add options to your command, provide a options definition as an argument ‘[–clean] [–env=] [-v] output_dir’ do |clean, env, v, output_dir| # parameters are matched based on name # clean contains a boolean # env contains a string or nil if not provided # v contains a number, counting the times it occurred in the arguments # output_dir contains a string, if needed to match this command end ```

Running the application

```ruby # filename: app.rb

create an application

app =

a build command ‘[–clean] [–env=] [-v] output_dir’ do |clean, env, v, output_dir| puts ‘Starting build…’ if v > 0

do_clean_up if clean

do_build env   ‘development’, output_dir

puts ‘Build complete’ if v > 0 end

a deploy command ‘[-v] [–env=]’ do |env| puts ‘Starting deploy…’ if v > 0

do_deploy env   ‘development’

puts ‘Deploy complete’ if v > 0 end ```

Shell commands: ```sh # start a build ruby app.rb build –env production dist


ruby app.rb deploy ```

Options definition

Option Meaning Example
-f Short option with name f ruby app.rb build -f
--clean Long option with name clean ruby app.rb build --clean
output_dir Argument with name output_dir ruby app.rb build dist/
--env= Long option with value ruby app.rb build --env production
-e= Short option with value ruby app.rb build -e production
[ .. ] Optional options/arguments ruby app.rb build would match [-v]

Optional-tokens can occur anywhere in the options, as long as they are not nested and properly closed. You can group optional parts, meaning that both options/arguments should be available or both not.

Options and/or arguments are mandatory unless specified otherwise.

Grouping of optionals allows you do things like this:

```ruby app = app.shout ‘[first_name last_name] [name]’ do |first_name, last_name, name| # by definition, last_name is also filled unless first_name.nil? then puts “Hello #first_name #last_name!” end

unless name.nil? then puts “Hello #name!” end end

calling with two arguments can fill the first group

# prints “Hello John Doe!”[‘shout’, ‘John’, ‘Doe’])

calling with one argument it is not possible to fill the first group

# prints “Hello Mr. White!”[‘shout’, ‘Mr. White!’]) ```

Return types in action block

Option type Return type (ex.) Default (if optional)
Short Integer (1) 0
Long Boolean (true) false
Value String (production) nil
Argument String (dist/) nil


To make application nesting possible you can provide a complete application to a command, instead of an action block.

```ruby # filename: app.rb

create a subapplication

android = do; end

options are supported just like regular apps

android.clean ‘–force’ do; end

create an application

app =

mount the android application on top of the android command

# note that the command does not support options android ```

You can now run the next bit to run the android build command:

sh ruby app.rb android build

You can build them as complicated as you like :)

Complete example

```ruby #!/usr/bin/env ruby

db = db.migrate ‘– run all pending migrations’ do run_migrate end

db.rollback ‘[–migrations=] – rollback a number of migrations’ do |migrations| run_rollback migrations || 1 end

cache = cache.clear ‘[–env=] – clear the cache for a given environment’ do |env| run_cache_clear env || ‘development’ end

cache.warmup ‘[–env=] – warmup the cache for a given environment’ do |env| run_cache_warmup env || ‘development’ end

app = app.db db app.cache cache ‘[–clean] [–env=] [-v] output_dir – build the project’ do |clean, env, v, output_dir| puts ‘Starting build…’ if v > 0

if clean puts ‘Starting clean…’ if v > 1 do_clean_up if clean end

do_build env   ‘development’, output_dir

puts ‘Build complete’ if v > 0 end ```

Make the file executable with chmod a+x app.rb, you can now call it with ./app.rb without ruby in front of it, saves a couple keystrokes.

sh # run all migration ./app.rb db migrate # rollback the last 4 migrations ./app.rb db rollback 4 # clean production cache ./app.rb cache clear --env production # build the project, including cleaning and logging ./app.rb build --clean --env production -vv dist/ # print the usage message ./app.rb

Current wish-list

  • Aliases, mostly to “document” short options, -v|--verbose

Final notes

If you like what you see, feel free to use it anyway you like. Also, don’t hold back if you have suggestions/question and create an issue to let me know, and we can talk about it. And if you don’t like what you see, PRs are welcome. You should probably file an issue first to make sure it’s something worth doing, and the right way to do it.