GLI allows you to create command-line app in Ruby that behaves like
git in that it takes subcommands to perform a series of complex action, e.g.
git remote add.
Creating a command-line app that uses subcommands, each of which might accept different command-line options, is somewhat difficult with Ruby's built-in
OptionParser. GLI provides an API that wraps
OptionParser so that you can create a subcommand-based command-line app with minimal boilerplate. This API also produces complete documentation for your command-line app.
There are other RubyGems that allow you to create a command-line app that takes subcommands. These solutions are often quite limited (e.g. they don't allow deeply nested subcommand structures or sophisticated command-line options per subcommand), or require more code that we think is needed. Some solutions make it difficult or impossible to properly document your command-line app.
You should know Ruby, and have a basic understanding of how the UNIX command line works: standard input, standard output, standard error, and exit codes.
Install if you need to:
gem install gli
You can validate you have installed it correctly by running
gli help. You should see formatted help output.
If you are using GLI in another application, add it to your
You can test your install via Bundler by running
bundle exec gli help. This should produce formatted help output from GLI.
The simplest way to get started is to create a scaffold project
gli init todo list add complete
(note if you installed via Bundler you will need to execute
bundle exec gli init todo list add complete)
This will create a basic scaffold project in
./todo/bin/todo. This file demonstrates most of what you need to describe your command line interface.
an empty test in
./todo/test/default_test.rbthat can bootstrap your tests
an empty feature in
./todo/features/todo.featurethat can bootstrap testing your CLI via Aruba.
a gemspec shell
a README shell
Rakefile that can generate RDoc, package your Gem and run tests
Gemfilesuitable for use with Bundler to manage development-time dependencies
Now, you are ready to go:
> cd todo > bundle exec bin/todo help NAME todo - Describe your application here SYNOPSIS todo [global options] command [command options] [arguments...] VERSION 0.0.1 GLOBAL OPTIONS -f, --flagname=The name of the argument - Describe some flag here (default: the default) --help - Show this message -s, --[no-]switch - Describe some switch here COMMANDS add - Describe add here complete - Describe complete here help - Shows a list of commands or help for one command list - Describe list here > bundle exec bin/todo help list NAME list - Describe list here SYNOPSIS todo [global options] list [command options] Describe arguments to list here COMMAND OPTIONS -f arg - Describe a flag to list (default: default) -s - Describe a switch to list
All you need to do is fill in the documentation and your code; the help system, command-line parsing and many other awesome features are all handled for you.
Get a more detailed walkthrough on the main site
Tests should be passing supported MRI Rubies (see
.travis.yml for specifics).
Due to the vagaries of Travis, I can't keep the test suite running on unsupported Rubies, but we currently support:
GLI likely works on older rubies, but the cost of keeping tests passing on those versions (which are now totally unsupported by Ruby core) is too high.
Extensive documentation is available at the wiki.
API Documentation is available here. Recommend starting with GLI::DSL or GLI::App.
Dave Copeland (davetron5000 at g mail dot com)
Copyright © 2010 by Dave Copeland
Distributes under the Apache License, see LICENSE.txt in the source distro
Source on GitHub