Formatting Help Messages

To format help messages, use the Help class.

For example:

class Smile < Cli::Command
  class Help
    header "Smiles n times."
    footer "(C) 20XX mosop"
  end

  class Options
    arg "face", required: true, desc: "your face, for example, :), :(, :P"
    string "--times", var: "NUMBER", default: "1", desc: "number of times to display"
    help
  end

  def run
    puts args.face * options.times.to_i
  end
end

Smile.run ARGV

If you run this command with a help option, you see:

$ smile --help
smile [OPTIONS] FACE

Smiles n times.

Arguments:
  FACE  your face, for example, :), :(, :P

Options:
  --times NUMBER  number of times to display
                  (default: 1)
  -h, --help      show this help

(C) 20XX mosop

Sections

The help format has the following sections. Each section is aligned in the order.

• title
• header
• subcommands (for supercommands only)
• arguments
• options
• footer

Title

By default, the title section is automatically generated. To explicitly specify a title, use the Help.title method.

class Ancient < Cli::Command
  class Help
    title "ancient - calls ancient people"
  end
end

Instead of specifying a whole title, you can only set a command's name. It is convenient when a command name is different from its class name.

class Main < Cli::Command
  command_name "ancient"
end

Note: The command_name method belongs to a command class, not the Help class.

Unparsed Arguments

You may make a command that has arguments unparsed. For example, "exec" command internally executes another command and passes unparsed arguments to the other command. If you still need to display unparsed arguments in a title, use the Help.unparsed_args method.

class Myexec < Cli::Command
  class Options
    arg "command", required: true, stop: true, desc: "command name"
    help
  end

  class Help
    unparsed_args "[ARG1 ARG2 ...]"
  end
end

Myexec.run %w(-h)

This prints:

myexec COMMAND [ARG1 ARG2 ...]

Arguments:
  COMMAND  command name

Options:
  -h, --help  show this help

Header and Footer

The header and footer sections are not automatically generated. They appear only if you define them.

To define those sections, use the methods: Help.header and Help.footer.

class Dependency < Cli::Command
  class Help
    header <<-EOS
      Renders a dependency diagram.

      Supported package managers:
        RubyGems
        Shards
        npm
      EOS
    footer <<-EOS
      (C) 20XX mosop
      Created by mosop (http://mosop.me)
      EOS
  end
end

Subcommands

The subcommands section is appeared only if a command is a supercommand.

You can specify a caption that is displayed beside each subcommand. The caption is a very short description and typically a single phrase.

class Cake < Cli::Supercommand
  command "strawberry"
  command "cheese"
  command "chocolat"

  class Options
    help
  end

  class Strawberry < Cli::Command
    class Help
      caption "made with Sachinoka strawberry"
    end
  end

  class Cheese < Cli::Command
    class Help
      caption "New York-style"
    end
  end

  class Chocolat < Cli::Command
    class Help
      caption "winter only"
    end
  end
end

Cake.run %w(--help)
# cake SUBCOMMAND
#
# Subcommands:
#   cheese      New York-style
#   chocolat    winter only
#   strawberry  made with Sachinoka strawberry
#
# Options:
#   -h, --help  show this help

Arguments and Options

The arguments and options sections are automatically generated from information defined.

You can specify an option's description by the :desc option.

class Friend < Cli::Command
  class Options
    arg "name", required: true, desc: "your friend name"
    string "--years", desc: "how long you've been friends"
    help
  end
end

Friend.run %w(--help)
# friend [OPTIONS] NAME
#
# Arguments:
#   NAME (required)  your friend name
#
# Options:
#   --years  how long you've been friends