Runfile - command line for your projects

---

A beautiful command line utility builder
Rake-inspired ✦ Docopt inside
runfile.dannyb.co

---

Runfile lets you create command line tools in a way similar to Rake, but with the full power of Docopt command line options.

You create a runfile, and execute commands with run command arguments -and --flags.

Runfile is designed primarily for Ruby developers, but if you need to add a command line "toolbelt" for your projects, you can use it regardless.

$ gem install runfile --pre

$ run new        # create a new runfile
$ run --help     # show the usage patterns
$ vi runfile     # edit the runfile

A simple runfile looks like this. You can get this template by running run new (in a directory without other runfiles).

title   'Greeter'
summary 'A sample runfile'

usage  'hello [NAME --shout]'
help   'Say hello'
option '--shout, -s', 'Greet louder'
action 'hello' do |args|
  name = args['NAME'] || 'You...'
  message = "Hello #{name}"
  message = "#{message.upcase}!" if args['--shout']

  say "gu`#{message}`"
end

You can then run it by executing this command:

$ run hello Luke
Hello Luke

It will behave in the same way you expect any standard command line interface to behave,

# Show usage summary
$ run
Usage:
  run hello [NAME --shout]
  run (--help | -h)

# Show detailed help
$ run --help
Greeter

  A sample runfile

Usage:
  run hello [NAME --shout]
  run (--help | -h)

Commands:
  hello
    Say hello

Options:
  --shout, -s
    Greet louder

  --help, -h
    Show this message

You can learn almost everything there is to know about runfile from the examples.

You can get any of these examples directly in your terminal by running:

$ run example --help

For a more formal documentation, see the User Guide.

If you are using a version earlier than 1.0, note that version 1.0.0 includes some breaking changes. You can read more about them in this Pull Request.

If you have used the multi-runfile config file, this no longer exists. Use a standard runfile instead, along with the import directive.

If you have used the action :global do notation, this is replaced with the simpler use action do instead. Also, there is no more need for empty usage '', just delete it if you have it in your runfiles.

If you have used it to cross-call other actions, it is no longer available. As an alternative, you can define common code in separate classes and require them, or use the new helpers directive to define functions that will be available to all actions.

If your runfiles include other ruby code, especially def method, you should now use the new helpers block and tuck this code inside it.

If your old runfiles trap the Interrupt signal, there is no longer a need to do so, as it is trapped by default.

If your runfiles required and include Colsole, there is no longer a need to do it. Colsole is bundled and available in actions.

This is a cosmetic change for consistency. All generated output shows long flags before short flags --force, -f instead of -f, --force. Update your custom usage directives accordingly.

If you were using the example directive, it will no longer add the initial run in front of your examples. Add it yourself. This is intended to allow providing more elaborate examples.

The runfile-tasks gem is also updated to 1.x, with a modified syntax. If you are using it, make sure to upgrade it as well.

If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.