command_kit 0.1.0.pre2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baf0cab5c4519bef85a5ac27597c1c67b28a77cbe86d6c34b72687a91e1ef906
-  data.tar.gz: 1b816bb979dcff48caf5c09ac7f4dcd9006871c94b9fd3bee5a7c2ce1763815a
+  metadata.gz: a218265a42b8b11c95888d07a3dcc3817d534adf830f8e7b1f1790bae73f05d6
+  data.tar.gz: c11cf5b2179d0701d5164b5ffcc07f2040cf8c813ea68caafdd7602e8603b754
 SHA512:
-  metadata.gz: 284c9a6ff6bb1584add29558658054fc0814cfc0b1a1609b16a577154bc85e7011d9989abc75418bbd631f00a5f6c444dd104b3d938be347ad32ddf08e84ec83
-  data.tar.gz: f0df98d7654058aa5be0aa884703ef540be3a1b7e2be52cd4a975913731ee4572d30cfc1a7b5213b9a165e7a18f95f4bbd3d9eb1a217362370a6c3b9e6c7ea93
+  metadata.gz: 7bd20d0e6b33b1d84933ea246c51b552c8652e3f59c8ec3fe32bf1944148377799b20b8177f0025114689ff5f73a88d08fe14171bdbd48189ab4123ba9129113
+  data.tar.gz: 617efce051bc51bbb88ada26a83ded0e158b8e0af28ab2bad8af1478aac05a156833aa3bfd95b59e7b07daf1075c08e60f7f6165cc28b76908cb13eb694c4f4b

data/.github/workflows/ruby.yml

@@ -3,6 +3,7 @@ name: CI
 on: [ push, pull_request ]
 
 jobs:
+  # run tests
   tests:
     runs-on: ubuntu-latest
     strategy:
@@ -27,3 +28,17 @@ jobs:
         run: bundle install --jobs 4 --retry 3
       - name: Run tests
         run: bundle exec rake test
+
+  # rubocop linting
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run rubocop
+        run: bundle exec rubocop --parallel

data/.rubocop.yml

@@ -0,0 +1,141 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.7
+
+#
+# our rules
+#
+
+Layout/FirstArrayElementIndentation: { EnforcedStyle: consistent }
+Layout/LineLength: { Enabled: false }
+Layout/SpaceAroundEqualsInParameterDefault: { EnforcedStyle: no_space }
+Lint/ConstantDefinitionInBlock: { Exclude: ['spec/**/*'] }
+Metrics: { Enabled: false }
+Style/SymbolArray: { EnforcedStyle: brackets }
+Style/IfInsideElse: { Enabled: false } # Offense count: 1
+Style/PercentLiteralDelimiters:
+  Enabled: true
+  PreferredDelimiters:
+    default: '{}'
+    '%i': '[]'
+    '%I': '[]'
+    '%w': '[]'
+    '%W': '[]'
+
+#
+# rules that are in flux
+#
+
+# consider enabling these and autocorrecting?
+# Layout/SpaceAfterComma
+# Layout/SpaceAroundKeyword
+# Layout/SpaceBeforeComma
+# Layout/SpaceInsideHashLiteralBraces
+# Layout/SpaceInsideParens
+# Layout/TrailingWhitespace
+# Lint/UnreachableLoop
+# Lint/UnusedBlockArgument
+# Style/ClassCheck
+# Style/Documentation
+# Style/ExpandPathArguments
+# Style/GlobalStdStream
+# Style/HashSyntax
+# Style/KeywordParametersOrder
+# Style/MethodCallWithoutArgsParentheses
+# Style/MutableConstant
+# Style/QuotedSymbols: { EnforcedStyle: double_quotes }
+# Style/RedundantReturn
+# Style/SafeNavigation
+# Style/SpecialGlobalVars
+# Style/StringLiterals: { EnforcedStyle: double_quotes }
+# Style/WordArray
+
+# these have been fixed
+# Gemspec/DuplicatedAssignment: { Enabled: false } # Offense count: 1
+# Layout/ElseAlignment: { Enabled: false } # Offense count: 1
+# Layout/EndAlignment: { Enabled: false } # Offense count: 1
+# Lint/DuplicateMethods: { Enabled: false } # Offense count: 1
+# Lint/UselessAssignment: { Enabled: false } # Offense count: 1
+# Style/Encoding: { Enabled: false } # Offense count: 2
+# Style/RedundantBegin: { Enabled: false } # Offense count: 2
+# Style/RedundantInterpolation: { Enabled: false } # Offense count: 1
+# Style/TrailingCommaInArrayLiteral: { Enabled: false } # Offense count: 1
+
+#
+# This list was generated with:
+# bundle exec rubocop --auto-gen-config --exclude-limit 1
+#
+
+# > 10 violations
+Layout/AssignmentIndentation: { Enabled: false } # Offense count: 11
+Layout/EmptyLinesAroundClassBody: { Enabled: false } # Offense count: 76
+Layout/HashAlignment: { Enabled: false } # Offense count: 28
+Layout/SpaceAfterComma: { Enabled: false } # Offense count: 141
+Layout/SpaceInsideHashLiteralBraces: { Enabled: false } # Offense count: 57
+Layout/TrailingWhitespace: { Enabled: false } # Offense count: 50
+Naming/RescuedExceptionsVariableName: { Enabled: false } # Offense count: 11
+Style/BlockDelimiters: { Enabled: false } # Offense count: 17
+Style/ClassCheck: { Enabled: false } # Offense count: 10
+Style/ClassEqualityComparison: { Enabled: false } # Offense count: 16
+Style/FrozenStringLiteralComment: { Enabled: false } # Offense count: 77
+Style/GlobalStdStream: { Enabled: false } # Offense count: 13
+Style/GuardClause: { Enabled: false } # Offense count: 10
+Style/IfUnlessModifier: { Enabled: false } # Offense count: 13
+Style/MethodCallWithoutArgsParentheses: { Enabled: false } # Offense count: 10
+Style/SpecialGlobalVars: { Enabled: false } # Offense count: 28
+Style/StringLiterals: { Enabled: false } # Offense count: 774
+Lint/ElseLayout: { Enabled: false } # Offense count: 22
+
+# < 10 violations
+Layout/EmptyLinesAroundModuleBody: { Enabled: false } # Offense count: 5
+Layout/ExtraSpacing: { Enabled: false } # Offense count: 6
+Layout/FirstHashElementIndentation: { Enabled: false } # Offense count: 4
+Layout/ParameterAlignment: { Enabled: false } # Offense count: 9
+Layout/SpaceAroundKeyword: { Enabled: false } # Offense count: 7
+Layout/SpaceBeforeComma: { Enabled: false } # Offense count: 4
+Layout/SpaceInsideParens: { Enabled: false } # Offense count: 4
+Lint/EmptyClass: { Enabled: false } # Offense count: 3
+Lint/SuppressedException: { Enabled: false } # Offense count: 4
+Lint/UnusedMethodArgument: { Enabled: false } # Offense count: 5
+Style/AccessorGrouping: { Enabled: false } # Offense count: 7
+Style/Documentation: { Enabled: false } # Offense count: 3
+Style/ExpandPathArguments: { Enabled: false } # Offense count: 8
+Style/HashSyntax: { Exclude: ['Rakefile'] } # Offense count: 3
+Style/KeywordParametersOrder: { Enabled: false } # Offense count: 8
+Style/Lambda: { Enabled: false } # Offense count: 3
+Style/MutableConstant: { Enabled: false } # Offense count: 4
+Style/RaiseArgs: { Enabled: false } # Offense count: 4
+Style/RedundantReturn: { Enabled: false } # Offense count: 7
+Style/SafeNavigation: { Enabled: false } # Offense count: 5
+Style/StringConcatenation: { Enabled: false } # Offense count: 8
+Style/WordArray: { Enabled: false } # Offense count: 4
+
+# 1 or 2 violations
+Layout/ArgumentAlignment: { Enabled: false } # Offense count: 1
+Layout/BlockAlignment: { Enabled: false } # Offense count: 1
+Layout/IndentationWidth: { Enabled: false } # Offense count: 2
+Layout/SpaceAroundOperators: { Enabled: false } # Offense count: 1
+Layout/SpaceBeforeBlockBraces: { Enabled: false } # Offense count: 1
+Lint/MissingSuper: { Enabled: false } # Offense count: 2
+Lint/RescueException: { Enabled: false } # Offense count: 1
+Lint/UnreachableLoop: { Enabled: false } # Offense count: 1
+Lint/UnusedBlockArgument: { Enabled: false } # Offense count: 1
+Naming/MethodParameterName: { Enabled: false } # Offense count: 1
+Style/EmptyMethod: { Enabled: false } # Offense count: 2
+Style/HashConversion: { Enabled: false } # Offense count: 1
+Style/MultilineMemoization: { Enabled: false } # Offense count: 1
+Style/NumericPredicate: { Enabled: false } # Offense count: 1
+Style/OptionalArguments: { Enabled: false } # Offense count: 1
+Style/ParenthesesAroundCondition: { Enabled: false } # Offense count: 1
+Style/PreferredHashMethods: { Enabled: false } # Offense count: 1
+Style/QuotedSymbols: { Enabled: false } # Offense count: 1
+Style/RedundantException: { Enabled: false } # Offense count: 1
+Style/RedundantRegexpEscape: { Enabled: false } # Offense count: 1
+Style/RegexpLiteral: { Enabled: false } # Offense count: 1
+Style/RescueStandardError: { Enabled: false } # Offense count: 1
+Style/SoleNestedConditional: { Enabled: false } # Offense count: 1
+Style/TrailingCommaInHashLiteral: { Enabled: false } # Offense count: 2
+
+# rubocop cannot tell that rubygems_mfa_required is enabled in gemspec.yml
+Gemspec/RequireMFA: { Enabled: false }

data/ChangeLog.md

@@ -1,13 +1,105 @@
-### 0.1.0 / 2021-05-XX
+### 0.2.1 / 2021-11-16
+
+* Ensure that all error messages end with a period.
+* Documentation fixes.
+* Opt-in to [rubygem.org MFA requirement](https://guides.rubygems.org/mfa-requirement-opt-in/).
+
+#### CommandKit::Printing
+
+* Auto-detect whether {CommandKit::CommandName#command_name #command_name} is
+  available, and if so, prepend the command name to all error messages.
+
+#### CommandKit::Help::Man
+
+* Expand the path given to
+  {CommandKit::Help::Man::ClassMethods#man_dir man_dir}.
+* If {CommandKit::Help::Man::ClassMethods#man_dir man_dir} is not set, fallback
+  to regular `--help` output.
+
+#### CommandKit::Arguments
+
+* Include {CommandKit::Usage} and {CommandKit::Printing} into
+  {CommandKit::Arguments}.
+
+#### CommandKit::Options
+
+* Include {CommandKit::Arguments} into {CommandKit::Options}.
+* Ensure that {CommandKit::Options::Parser#main} runs before
+  {CommandKit::Arguments#main}.
+* Ensure that {CommandKit::Options#help} also calls
+  {CommandKit::Arguments#help_arguments}.
+* Always prepopulate {CommandKit::Options#options #options} with option's
+  default values.
+  * Note: if an option has a default value but the option's value is not
+    required (ex: `value: {required: false, default: "foo"}`), and the option's
+    flag is given but no value is given (ex: `--option-flag --some-other-flag`),
+    the option's value in {CommandKit::Options#options #options} will be `nil`
+    _not_ the option's default value (`"foo"`). This helps indicate that the
+    option's flag was given but no value was given with it.
+
+#### CommandKit::Options::OptionValue
+
+* When a `Class` is passed to {CommandKit::Options::OptionValue.default_usage},
+  demodularize the class name before converting it to underscored/uppercase.
+
+#### CommandKit::Command
+
+* Fixed the inclusion order of {CommandKit::Options} and
+  {CommandKit::Arguments}.
+
+#### CommandKit::Commands
+
+* Define the `COMMAND` and `ARGS` arguments.
+* Correctly duplicate the {CommandKit::Env#env env} (which can be either `ENV`
+  or a `Hash`) to work on ruby-3.1.0-preview1.
+* Print command aliases that were set explicitly
+  (ex: `command_aliases['rm'] = 'remove'`) in {CommandKit::Commands#help}.
+* Print help and exit with status `1` if no command is given. This matches the
+  behavior of the `git` command.
+
+#### CommandKit::Commands::AutoLoad
+
+* Ensure that any explicit command aliases are added to the command's
+  {CommandKit::Commands::ClassMethods#command_aliases command_aliases}.
+
+### 0.2.0 / 2021-08-31
+
+* Added {CommandKit::Colors::ANSI#on_black}.
+* Added {CommandKit::Colors::ANSI#on_red}.
+* Added {CommandKit::Colors::ANSI#on_green}.
+* Added {CommandKit::Colors::ANSI#on_yellow}.
+* Added {CommandKit::Colors::ANSI#on_blue}.
+* Added {CommandKit::Colors::ANSI#on_magenta}.
+* Added {CommandKit::Colors::ANSI#on_cyan}.
+* Added {CommandKit::Colors::ANSI#on_white}.
+* Added {CommandKit::Man}.
+* Added {CommandKit::OS#bsd?}.
+* Added {CommandKit::OS#freebsd?}.
+* Added {CommandKit::OS#netbsd?}.
+* Added {CommandKit::OS#openbsd?}.
+* Added {CommandKit::OS#os}.
+* Added {CommandKit::OS#unix?}.
+* Added {CommandKit::OS::Linux}.
+* Added {CommandKit::OpenApp}.
+* Added {CommandKit::PackageManager}.
+* Added {CommandKit::Pager#pipe_to_pager}.
+* Added {CommandKit::Sudo}.
+* Added {CommandKit::Terminal#tty?}.
+* Refactor {CommandKit::Inflector.camelize} and
+  {CommandKit::Inflector.underscore} to use StringScanner.
+* Allow {CommandKit::OS#initialize} to accept an `os:` keyword to override the
+  detected OS.
+
+### 0.1.0 / 2021-07-16
 
 * Initial release:
   * {CommandKit::Arguments}
   * {CommandKit::Colors}
+  * {CommandKit::Command}
   * {CommandKit::CommandName}
   * {CommandKit::Commands}
     * {CommandKit::Commands::AutoLoad}
     * {CommandKit::Commands::AutoRequire}
-  * {CommandKit::Console}
   * {CommandKit::Description}
   * {CommandKit::Env}
     * {CommandKit::Env::Home}
@@ -16,14 +108,18 @@
   * {CommandKit::ExceptionHandler}
   * {CommandKit::Help}
     * {CommandKit::Help::Man}
+  * {CommandKit::Interactive}
   * {CommandKit::Main}
   * {CommandKit::Options}
     * {CommandKit::Options::Quiet}
     * {CommandKit::Options::Verbose}
+  * {CommandKit::OS}
   * {CommandKit::Pager}
   * {CommandKit::Printing}
+    * {CommandKit::Printing::Indent}
   * {CommandKit::ProgramName}
   * {CommandKit::Stdio}
+  * {CommandKit::Terminal}
   * {CommandKit::Usage}
   * {CommandKit::XDG}
 

data/Gemfile

@@ -6,9 +6,12 @@ group :development do
   gem 'rake'
   gem 'rubygems-tasks', '~> 0.2'
 
+  gem 'rubocop', '~> 1.18'
+
   gem 'rspec', '~> 3.0'
   gem 'simplecov', '~> 0.20', require: false
 
   gem 'kramdown'
   gem 'yard', '~> 0.9'
+  gem 'yard-spellcheck', require: false
 end

data/README.md

@@ -1,60 +1,41 @@
 # command_kit
 
-* [Homepage](https://github.com/postmodern/command_kit#readme)
-* [Issues](https://github.com/postmodern/command_kit/issues)
+[![Build Status](https://github.com/postmodern/command_kit.rb/workflows/CI/badge.svg?branch=main)](https://github.com/postmodern/command_kit.rb/actions)
+[![Code Climate](https://codeclimate.com/github/postmodern/command_kit.rb.svg)](https://codeclimate.com/github/postmodern/command_kit.rb)
+[![Gem Version](https://badge.fury.io/rb/command_kit.svg)](https://badge.fury.io/rb/command_kit)
+
+* [Homepage](https://github.com/postmodern/command_kit.rb#readme)
+* [Forum](https://github.com/postmodern/command_kit.rb/discussions) |
+  [Issues](https://github.com/postmodern/command_kit.rb/issues)
 * [Documentation](http://rubydoc.info/gems/command_kit/frames)
-* [Email](mailto:postmodern.mod3 at gmail.com)
 
 ## Description
 
-A Ruby toolkit for building clean, correct, and robust CLI commands as Ruby
-classes.
+A Ruby toolkit for building clean, correct, and robust CLI commands as
+plain-old Ruby classes.
 
 ## Features
 
-* Supports defining commands as Classes.
-* Supports defining options and arguments as attributes.
-* Supports extending commands via inheritance.
-* Supports subcommands (explicit or lazy-loaded) and command aliases.
-* Correctly handles Ctrl^C and SIGINT interrupts (aka exit 130).
-* Correctly handles broken pipes (aka `mycmd | head`).
-* Uses [OptionParser][optparse] for option parsing.
-* Provides ANSI coloring support.
-* Supports optionally displaying a man-page instead of `--help`
-  (see {CommandKit::Help::Man}).
-* Supports XDG directories (`~/.config/`, `~/.local/share/`, `~/.cache/`).
-* Easy to test (ex: `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`)
-* Modular design (everything is a module).
-
-### API
-
-* [CommandKit::Arguments](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Arguments)
-* [CommandKit::Colors](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Colors)
-* [CommandKit::Command](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Command)
-* [CommandKit::CommandName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/CommandName)
-* [CommandKit::Commands](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands)
-  * [CommandKit::Commands::AutoLoad](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoLoad)
-  * [CommandKit::Commands::AutoRequire](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoRequire)
-* [CommandKit::Console](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Console)
-* [CommandKit::Description](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Description)
-* [CommandKit::Env](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env)
-  * [CommandKit::Env::Home](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Home)
-  * [CommandKit::Env::Path](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Path)
-* [CommandKit::Examples](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Examples)
-* [CommandKit::ExceptionHandler](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ExceptionHandler)
-* [CommandKit::Help](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help)
-  * [CommandKit::Help::Man](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help/Man)
-* [CommandKit::Main](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Main)
-* [CommandKit::Options](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options)
-  * [CommandKit::Options::Quiet](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Quiet)
-  * [CommandKit::Options::Verbose](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Verbose)
-* [CommandKit::Pager](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Pager)
-* [CommandKit::Printing](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing)
-  * [CommandKit::Printing::Indent](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing/Indent)
-* [CommandKit::ProgramName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ProgramName)
-* [CommandKit::Stdio](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Stdio)
-* [CommandKit::Usage](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Usage)
-* [CommandKit::XDG](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/XDG)
+* **Simple** - Commands are plain-old ruby classes, with options and
+  arguments declared as attributes. All features are ruby modules that can be
+  included into command classes.
+* **Correct** - CommandKit behaves like a standard UNIX command.
+  * Safely handles Ctrl^C / SIGINT interrupts and [exits with 130](https://tldp.org/LDP/abs/html/exitcodes.html).
+  * Safely handles broken pipes (aka `mycmd | head`).
+  * Respects common environment variables (ex: `TERM=dumb`).
+  * Uses [OptionParser][optparse] for POSIX option parsing.
+  * Disables ANSI color when output is redirected to a file.
+* **Complete** - Provides many additional CLI features.
+  * OS detection.
+  * Terminal size detection.
+  * ANSI coloring support.
+  * Interactive input.
+  * Subcommands (explicit or lazy-loaded) and command aliases.
+  * Displaying man pages for `--help`/`help`.
+  * Using the pager (aka `less`).
+  * [XDG directories](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) (aka `~/.config/`, `~/.local/share/`, `~/.cache/`).
+* **Testable** - Since commands are plain-old ruby classes, it's easy to
+  initialize them and call `#main` or `#run`.
 
 ## Anti-Features
 
@@ -62,103 +43,194 @@ classes.
 * Does not implement it's own option parser.
 * Not named after a comic-book Superhero.
 
+## Requirements
+
+* [ruby] >= 2.7.0
+
+## Install
+
+```sh
+$ gem install command_kit
+```
+
+### gemspec
+
+```ruby
+gem.add_dependency 'command_kit', '~> 0.2'
+```
+
+### Gemfile
+
+```ruby
+gem 'command_kit', '~> 0.2'
+```
+
 ## Examples
 
 ### lib/foo/cli/my_cmd.rb
 
-    require 'command_kit'
-
-    module Foo
-      module CLI
-        class MyCmd < CommandKit::Command
-    
-          usage '[OPTIONS] [-o OUTPUT] FILE'
-    
-          option :count, short: '-c',
-                         value: {
-                           type: Integer,
-                           default: 1
-                         },
-                         desc: "Number of times"
-    
-          option :output, short: '-o',
-                          value: {
-                            type: String,
-                            usage: 'FILE'
-                          },
-                          desc: "Optional output file"
-    
-          option :verbose, short: '-v', desc: "Increase verbose level" do
-            @verbose += 1
-          end
-    
-          argument :file, required: true,
-                          usage: 'FILE',
-                          desc: "Input file"
-
-          examples [
-            '-o path/to/output.txt path/to/input.txt',
-            '-v -c 2 -o path/to/output.txt path/to/input.txt',
-          ]
-
-          description 'Example command'
-    
-          def initialize(**kwargs)
-            super(**kwargs)
-    
-            @verbose = 0
-          end
-    
-          def run(file)
-            puts "count=#{options[:count].inspect}"
-            puts "output=#{options[:output].inspect}"
-            puts "file=#{file.inspect}"
-            puts "verbose=#{@verbose.inspect}"
-          end
-    
-        end
+```ruby
+require 'command_kit'
+
+module Foo
+  module CLI
+    class MyCmd < CommandKit::Command
+
+      usage '[OPTIONS] [-o OUTPUT] FILE'
+
+      option :count, short: '-c',
+                     value: {
+                       type: Integer,
+                       default: 1
+                     },
+                     desc: "Number of times"
+
+      option :output, short: '-o',
+                      value: {
+                        type: String,
+                        usage: 'FILE'
+                      },
+                      desc: "Optional output file"
+
+      option :verbose, short: '-v', desc: "Increase verbose level" do
+        @verbose += 1
       end
+
+      argument :file, required: true,
+                      usage: 'FILE',
+                      desc: "Input file"
+
+      examples [
+        '-o path/to/output.txt path/to/input.txt',
+        '-v -c 2 -o path/to/output.txt path/to/input.txt',
+      ]
+
+      description 'Example command'
+
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @verbose = 0
+      end
+
+      def run(file)
+        puts "count=#{options[:count].inspect}"
+        puts "output=#{options[:output].inspect}"
+        puts "file=#{file.inspect}"
+        puts "verbose=#{@verbose.inspect}"
+      end
+
     end
+  end
+end
+```
 
 ### bin/my_cmd
 
-    #!/usr/bin/env ruby
-    
-    $LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
-    require 'foo/cli/my_cmd'
-    
-    Foo::CLI::MyCmd.start
+```ruby
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
+require 'foo/cli/my_cmd'
+
+Foo::CLI::MyCmd.start
+```
 
 ### --help
 
     Usage: my_cmd [OPTIONS] [-o OUTPUT] FILE
-    
+
     Options:
         -c, --count INT                  Number of times (Default: 1)
         -o, --output FILE                Optional output file
         -v, --verbose                    Increase verbose level
         -h, --help                       Print help information
-    
+
     Arguments:
         FILE                             Input file
-    
+
     Examples:
         my_cmd -o path/to/output.txt path/to/input.txt
         my_cmd -v -c 2 -o path/to/output.txt path/to/input.txt
-    
-    Example command
 
-## Requirements
-
-* [ruby] >= 2.7.0
+    Example command
 
-## Install
+## Testing
+
+### RSpec
+
+```ruby
+require 'spec_helper'
+require 'stringio'
+require 'foo/cli/my_cmd'
+
+describe Foo::CLI::MyCmd do
+  let(:stdin)  { StringIO.new }
+  let(:stdout) { StringIO.new }
+  let(:stderr) { StringIO.new }
+  let(:env)    { ENV }
+
+  subject do
+    described_class.new(
+      stdin:   stdin,
+      stdout:  stdout,
+      stderr:  stderr,
+      env:     env
+    )
+  end
+
+  # testing with raw options/arguments
+  describe "#main" do
+    context "when executed with no arguments" do
+      it "must exit with -1" do
+        expect(subject.main([])).to eq(-1)
+      end
+    end
 
-    $ gem install command_kit
+    context "when executed with -o OUTPUT" do
+      let(:file)   { ... }
+      let(:output) { ... }
 
-### Gemfile
+      before { subject.main(["-o", output, file]) }
 
-    gem 'command_kit', '~> 0.1'
+      it "must create the output file" do
+        ...
+      end
+    end
+  end
+end
+```
+
+### Reference
+
+* [CommandKit::Arguments](https://rubydoc.info/gems/command_kit/CommandKit/Arguments)
+* [CommandKit::Colors](https://rubydoc.info/gems/command_kit/CommandKit/Colors)
+* [CommandKit::Command](https://rubydoc.info/gems/command_kit/CommandKit/Command)
+* [CommandKit::CommandName](https://rubydoc.info/gems/command_kit/CommandKit/CommandName)
+* [CommandKit::Commands](https://rubydoc.info/gems/command_kit/CommandKit/Commands)
+  * [CommandKit::Commands::AutoLoad](https://rubydoc.info/gems/command_kit/CommandKit/Commands/AutoLoad)
+  * [CommandKit::Commands::AutoRequire](https://rubydoc.info/gems/command_kit/CommandKit/Commands/AutoRequire)
+* [CommandKit::Description](https://rubydoc.info/gems/command_kit/CommandKit/Description)
+* [CommandKit::Env](https://rubydoc.info/gems/command_kit/CommandKit/Env)
+  * [CommandKit::Env::Home](https://rubydoc.info/gems/command_kit/CommandKit/Env/Home)
+  * [CommandKit::Env::Path](https://rubydoc.info/gems/command_kit/CommandKit/Env/Path)
+* [CommandKit::Examples](https://rubydoc.info/gems/command_kit/CommandKit/Examples)
+* [CommandKit::ExceptionHandler](https://rubydoc.info/gems/command_kit/CommandKit/ExceptionHandler)
+* [CommandKit::Help](https://rubydoc.info/gems/command_kit/CommandKit/Help)
+  * [CommandKit::Help::Man](https://rubydoc.info/gems/command_kit/CommandKit/Help/Man)
+* [CommandKit::Interactive](https://rubydoc.info/gems/command_kit/CommandKit/Interactive)
+* [CommandKit::Main](https://rubydoc.info/gems/command_kit/CommandKit/Main)
+* [CommandKit::Options](https://rubydoc.info/gems/command_kit/CommandKit/Options)
+  * [CommandKit::Options::Quiet](https://rubydoc.info/gems/command_kit/CommandKit/Options/Quiet)
+  * [CommandKit::Options::Verbose](https://rubydoc.info/gems/command_kit/CommandKit/Options/Verbose)
+* [CommandKit::Pager](https://rubydoc.info/gems/command_kit/CommandKit/Pager)
+* [CommandKit::Printing](https://rubydoc.info/gems/command_kit/CommandKit/Printing)
+  * [CommandKit::Printing::Indent](https://rubydoc.info/gems/command_kit/CommandKit/Printing/Indent)
+* [CommandKit::ProgramName](https://rubydoc.info/gems/command_kit/CommandKit/ProgramName)
+* [CommandKit::Stdio](https://rubydoc.info/gems/command_kit/CommandKit/Stdio)
+* [CommandKit::Terminal](https://rubydoc.info/gems/command_kit/CommandKit/Terminal)
+* [CommandKit::Usage](https://rubydoc.info/gems/command_kit/CommandKit/Usage)
+* [CommandKit::XDG](https://rubydoc.info/gems/command_kit/CommandKit/XDG)
 
 ## Alternatives