Error Handling

You don't need to do anything special to message the user about errors (though it's polite to use the standard error when doing so). If you need to exit immediately due to an unrecoverable error, simply raise an exception; GLI will display the exception message to the user, but not the backtrace. In general, this is what you want and should work fine.

GLI will exit zero if no exception was raised. GLI will exit nonzero as follows:

• If there is a problem parsing the command line (e.g. unknown command, unknown flag), GLI exits with -1
• If your code raises an exception, GLI exits with -2

Custom Exit Codes

To skip GLI's exit status handling, instead of just raising an exception, do one of the following:

• exit_now!(message,exit_code)
• raise CustomExit(message,exit_code)

In both cases, the message will be displayed to the user as if you raised any other exception, and GLI will cause your program to exit with the status code provided.

Migrating older GLI-powered applications

The exit status is implemented as a return value from GLI.run. This means that your existing application will need to exit with the return value. In other words change this:

GLI.run(ARGV)

to this:

exit GLI.run(ARGV)

Debugging installed GLI applications

Unless you have overridden the on_error hook, GLI will not make the backtrace of any exceptions caught available. To cause GLI to print it, set the environment variable 'GLI_DEBUG' to 'true'.

$ bin/gli foo
error: Unknown command 'foo'
$ env GLI_DEBUG=true bin/gli foo
error: Unknown command 'foo'
/Users/davec/Projects/gli/lib/gli.rb:305:in `parse_options_helper': Unknown command 'foo' (GLI::BadCommandLine)
	from /Users/davec/Projects/gli/lib/gli.rb:244:in `parse_options'
	from /Users/davec/Projects/gli/lib/gli.rb:139:in `run'
	from bin/gli:70