{"id":13483215,"url":"https://github.com/commander-rb/commander","last_synced_at":"2025-03-27T14:30:42.154Z","repository":{"id":29510020,"uuid":"33048276","full_name":"commander-rb/commander","owner":"commander-rb","description":"The complete solution for Ruby command-line executables","archived":false,"fork":false,"pushed_at":"2024-01-15T23:30:13.000Z","size":1010,"stargazers_count":820,"open_issues_count":10,"forks_count":68,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-20T19:30:54.958Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commander-rb.png","metadata":{"files":{"readme":"README.md","changelog":"History.rdoc","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-28T20:03:28.000Z","updated_at":"2025-03-14T23:58:27.000Z","dependencies_parsed_at":"2024-06-18T11:27:20.865Z","dependency_job_id":null,"html_url":"https://github.com/commander-rb/commander","commit_stats":{"total_commits":844,"total_committers":52,"mean_commits":16.23076923076923,"dds":0.3210900473933649,"last_synced_commit":"98dee54912730397d06eca9132dbfd2ec3bbd4b0"},"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commander-rb%2Fcommander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commander-rb%2Fcommander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commander-rb%2Fcommander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commander-rb%2Fcommander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commander-rb","download_url":"https://codeload.github.com/commander-rb/commander/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245862956,"owners_count":20684759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:09.139Z","updated_at":"2025-03-27T14:30:42.105Z","avatar_url":"https://github.com/commander-rb.png","language":"Ruby","readme":"[\u003cimg src=\"https://api.travis-ci.org/commander-rb/commander.svg\" alt=\"Build Status\" /\u003e](https://travis-ci.org/commander-rb/commander)\n[![Inline docs](https://inch-ci.org/github/commander-rb/commander.svg)](https://inch-ci.org/github/commander-rb/commander)\n\n# Commander\n\nThe complete solution for Ruby command-line executables.\nCommander bridges the gap between other terminal related libraries\nyou know and love (OptionParser, HighLine), while providing many new\nfeatures, and an elegant API.\n\n## Features\n\n* Easier than baking cookies\n* Parses options using OptionParser\n* Auto-populates struct with options ( no more `{ |v| options[:recursive] = v }` )\n* Auto-generates help documentation via pluggable help formatters\n* Optional default command when none is present\n* Global / Command level options\n* Packaged with two help formatters (Terminal, TerminalCompact)\n* Imports the highline gem for interacting with the terminal\n* Adds additional user interaction functionality\n* Highly customizable progress bar with intuitive, simple usage\n* Multi-word command name support such as `drupal module install MOD`, rather than `drupal module_install MOD`\n* Sexy paging for long bodies of text\n* Support for MacOS text-to-speech\n* Command aliasing (very powerful, as both switches and arguments can be used)\n* Growl notification support for MacOS\n* Use the `commander` executable to initialize a commander driven program\n\n## Installation\n\n    $ gem install commander\n\n## Quick Start\n\nTo generate a quick template for a commander app, run:\n\n    $ commander init yourfile.rb\n\nTo generate a quick modular style template for a commander app, run:\n\n    $ commander init --modular yourfile.rb\n\n## Example\n\nFor more option examples view the `Commander::Command#option` method. Also\nan important feature to note is that action may be a class to instantiate,\nas well as an object, specifying a method to call, so view the RDoc for more information.\n\n### Classic style\n\n```ruby\nrequire 'rubygems'\nrequire 'commander/import'\n\n# :name is optional, otherwise uses the basename of this executable\nprogram :name, 'Foo Bar'\nprogram :version, '1.0.0'\nprogram :description, 'Stupid command that prints foo or bar.'\n\ncommand :foo do |c|\n  c.syntax = 'foobar foo'\n  c.description = 'Displays foo'\n  c.action do |args, options|\n    say 'foo'\n  end\nend\n\ncommand :bar do |c|\n  c.syntax = 'foobar bar [options]'\n  c.description = 'Display bar with optional prefix and suffix'\n  c.option '--prefix STRING', String, 'Adds a prefix to bar'\n  c.option '--suffix STRING', String, 'Adds a suffix to bar'\n  c.action do |args, options|\n    options.default :prefix =\u003e '(', :suffix =\u003e ')'\n    say \"#{options.prefix}bar#{options.suffix}\"\n  end\nend\n```\n\nExample output:\n\n```\n$ foobar bar\n# =\u003e (bar)\n\n$ foobar bar --suffix '}' --prefix '{'\n# =\u003e {bar}\n```\n\n### Modular style\n\n**NOTE:** Make sure to use `require 'commander'` rather than `require 'commander/import'`, otherwise Commander methods will still be imported into the global namespace.\n\n```ruby\nrequire 'rubygems'\nrequire 'commander'\n\nclass MyApplication\n  include Commander::Methods\n\n  def run\n    program :name, 'Foo Bar'\n    program :version, '1.0.0'\n    program :description, 'Stupid command that prints foo or bar.'\n\n    command :foo do |c|\n      c.syntax = 'foobar foo'\n      c.description = 'Displays foo'\n      c.action do |args, options|\n        say 'foo'\n      end\n    end\n\n    run!\n  end\nend\n\nMyApplication.new.run if $0 == __FILE__\n```\n\n### Block style\n\n```ruby\nrequire 'rubygems'\nrequire 'commander'\n\nCommander.configure do\n  program :name, 'Foo Bar'\n  program :version, '1.0.0'\n  program :description, 'Stupid command that prints foo or bar.'\n\n  # see classic style example for options\nend\n```\n\n## HighLine\n\nAs mentioned above, the highline gem is imported into the global scope. Here\nare some quick examples for how to utilize highline in your commands:\n\n```ruby\n# Ask for password masked with '*' character\nask(\"Password:  \") { |q| q.echo = \"*\" }\n\n# Ask for password\nask(\"Password:  \") { |q| q.echo = false }\n\n# Ask if the user agrees (yes or no)\nagree(\"Do something?\")\n\n# Asks on a single line (note the space after ':')\nask(\"Name: \")\n\n# Asks with new line after \"Description:\"\nask(\"Description:\")\n\n# Calls Date#parse to parse the date string passed\nask(\"Birthday? \", Date)\n\n# Ensures Integer is within the range specified\nask(\"Age? \", Integer) { |q| q.in = 0..105 }\n\n# Asks for a list of strings, converts to array\nask(\"Fav colors?\", Array)\n```\n\n## HighLine \u0026 Interaction Additions\n\nIn addition to highline's fantastic choice of methods, commander adds the\nfollowing methods to simplify common tasks:\n\n```ruby\n# Ask for password\npassword\n\n# Ask for password with specific message and mask character\npassword \"Enter your password please:\", '-'\n\n# Ask for CLASS, which may be any valid class responding to #parse. Date, Time, Array, etc\nnames = ask_for_array 'Names: '\nbday = ask_for_date 'Birthday?: '\n\n# Simple progress bar (Commander::UI::ProgressBar)\nuris = %w[\n  http://vision-media.ca\n  http://google.com\n  http://yahoo.com\n]\nprogress uris do |uri|\n  res = open uri\n  # Do something with response\nend\n\n# 'Log' action to stdout\nlog \"create\", \"path/to/file.rb\"\n\n# Enable paging of output after this point\nenable_paging\n\n# Ask editor for input (EDITOR environment variable or whichever is available: TextMate, vim, vi, emacs, nano, pico)\nask_editor\n\n# Ask editor, supplying initial text\nask_editor 'previous data to update'\n\n# Ask editor, preferring a specific editor\nask_editor 'previous data', 'vim'\n\n# Choose from an array of elements\nchoice = choose(\"Favorite language?\", :ruby, :perl, :js)\n\n# Alter IO for the duration of the block\nio new_input, new_output do\n  new_input_contents = $stdin.read\n  puts new_input_contents # outputs to new_output stream\nend\n# $stdin / $stdout reset back to original streams\n\n# Speech synthesis\nspeak 'What is your favorite food? '\nfood = ask 'favorite food?: '\nspeak \"Wow, I like #{food} too. We have so much in common.\"\nspeak \"I like #{food} as well!\", \"Victoria\", 190\n\n# Execute arbitrary applescript\napplescript 'foo'\n\n# Converse with speech recognition server\ncase converse 'What is the best food?', :cookies =\u003e 'Cookies', :unknown =\u003e 'Nothing'\nwhen :cookies\n  speak 'o.m.g. you are awesome!'\nelse\n  case converse 'That is lame, shall I convince you cookies are the best?', :yes =\u003e 'Ok', :no =\u003e 'No', :maybe =\u003e 'Maybe another time'\n  when :yes\n    speak 'Well you see, cookies are just fantastic, they melt in your mouth.'\n  else\n    speak 'Ok then, bye.'\n  end\nend\n```\n\n## Growl Notifications\n\nCommander provides methods for displaying Growl notifications. To use these\nmethods you need to install https://github.com/tj/growl which utilizes\nthe [growlnotify](https://growl.info/extras.php#growlnotify) executable. Note that\ngrowl is auto-imported by Commander when available, no need to require.\n\n```ruby\n# Display a generic Growl notification\nnotify 'Something happened'\n\n# Display an 'info' status notification\nnotify_info 'You have #{emails.length} new email(s)'\n\n# Display an 'ok' status notification\nnotify_ok 'Gems updated'\n\n# Display a 'warning' status notification\nnotify_warning '1 gem failed installation'\n\n# Display an 'error' status notification\nnotify_error \"Gem #{name} failed\"\n```\n\n## Commander Goodies\n\n### Option Defaults\n\nThe options struct passed to `#action` provides a `#default` method, allowing you\nto set defaults in a clean manner for options which have not been set.\n\n```ruby\ncommand :foo do |c|\n  c.option '--interval SECONDS', Integer, 'Interval in seconds'\n  c.option '--timeout SECONDS', Integer, 'Timeout in seconds'\n  c.action do |args, options|\n    options.default \\\n      :interval =\u003e 2,\n      :timeout  =\u003e 60\n  end\nend\n```\n\n### Command Aliasing\n\nAliases can be created using the `#alias_command` method like below:\n\n```ruby\ncommand :'install gem' do |c|\n  c.action { puts 'foo' }\nend\nalias_command :'gem install', :'install gem'\n```\n\nOr more complicated aliases can be made, passing any arguments\nas if it was invoked via the command line:\n\n```ruby\ncommand :'install gem' do |c|\n  c.syntax = 'install gem \u003cname\u003e [options]'\n  c.option '--dest DIR', String, 'Destination directory'\n  c.action { |args, options| puts \"installing #{args.first} to #{options.dest}\" }\nend\nalias_command :update, :'install gem', 'rubygems', '--dest', 'some_path'\n```\n\n```\n$ foo update\n# =\u003e installing rubygems to some_path\n```\n\n### Command Defaults\n\nAlthough working with a command executable framework provides many\nbenefits over a single command implementation, sometimes you still\nwant the ability to create a terse syntax for your command. With that\nin mind we may use `#default_command` to help with this. Considering\nour previous `:'install gem'` example:\n\n```ruby\ndefault_command :update\n```\n\n```\n$ foo\n# =\u003e installing rubygems to some_path\n```\n\nKeeping in mind that commander searches for the longest possible match\nwhen considering a command, so if you were to pass arguments to foo\nlike below, expecting them to be passed to `:update`, this would be incorrect,\nand would end up calling `:'install gem'`, so be careful that the users do\nnot need to use command names within the arguments.\n\n```\n$ foo install gem\n# =\u003e installing  to\n```\n\n### Long descriptions\n\nIf you need to have a long command description, keep your short description under `summary`, and consider multi-line strings for `description`:\n\n```ruby\n  program :summary, 'Stupid command that prints foo or bar.'\n  program :description, %q(\n#{c.summary}\n\nMore information about that stupid command that prints foo or bar.\n\nAnd more\n  )\n```\n\n### Additional Global Help\n\nArbitrary help can be added using the following `#program` symbol:\n\n```ruby\nprogram :help, 'Author', 'TJ Holowaychuk \u003ctj@vision-media.ca\u003e'\n```\n\nWhich will output the rest of the help doc, along with:\n\n    AUTHOR:\n\n      TJ Holowaychuk \u003ctj@vision-media.ca\u003e\n\n### Global Options\n\nAlthough most switches will be at the command level, several are available by\ndefault at the global level, such as `--version`, and `--help`. Using\n`#global_option` you can add additional global options:\n\n```ruby\nglobal_option('-c', '--config FILE', 'Load config data for your commands to use') { |file| ... }\n```\n\nThis method accepts the same syntax as `Commander::Command#option` so check it out for documentation.\n\nAll global options regardless of providing a block are accessable at the command level. This\nmeans that instead of the following:\n\n```ruby\nglobal_option('--verbose') { $verbose = true }\n...\nc.action do |args, options|\n  say 'foo' if $verbose\n...\n```\n\nYou may:\n\n```ruby\nglobal_option '--verbose'\n...\nc.action do |args, options|\n  say 'foo' if options.verbose\n...\n```\n\n### Formatters\n\nTwo core formatters are currently available, the default `Terminal` formatter\nas well as `TerminalCompact`. To utilize a different formatter simply use\n`:help_formatter` like below:\n\n```ruby\nprogram :help_formatter, Commander::HelpFormatter::TerminalCompact\n```\n\nOr utilize the help formatter aliases:\n\n```ruby\nprogram :help_formatter, :compact\n```\n\nThis abstraction could be utilized to generate HTML documentation for your executable.\n\n### Tracing\n\nBy default the `-t` and `--trace` global options are provided to allow users to get a backtrace to aid debugging.\n\nYou can disable these options:\n\n```ruby\nnever_trace!\n```\n\nOr make it always on:\n\n```ruby\nalways_trace!\n```\n\n## Tips\n\nWhen adding a global or command option, OptionParser implicitly adds a small\nswitch even when not explicitly created, for example `-c` will be the same as\n`--config` in both examples, however `-c` will only appear in the documentation\nwhen explicitly assigning it.\n\n```ruby\nglobal_option '-c', '--config FILE'\nglobal_option '--config FILE'\n```\n\n## ASCII Tables\n\nFor feature rich ASCII tables for your terminal app check out the terminal-table gem at https://github.com/tj/terminal-table\n\n    +----------+-------+----+--------+-----------------------+\n    | Terminal | Table | Is | Wicked | Awesome               |\n    +----------+-------+----+--------+-----------------------+\n    |          |       |    |        | get it while its hot! |\n    +----------+-------+----+--------+-----------------------+\n\n## Running Specifications\n\n    $ rake spec\n\nOR\n\n    $ spec --color spec\n\n## Contrib\n\nFeel free to fork and request a pull, or submit a ticket\nhttps://github.com/commander-rb/commander/issues\n\n## License\n\nThis project is available under the MIT license. See LICENSE for details.\n","funding_links":[],"categories":["Ruby","CLI Builder","[Ruby](https://www.ruby-lang.org/)"],"sub_categories":["Useful awesome list for Go cli"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommander-rb%2Fcommander","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommander-rb%2Fcommander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommander-rb%2Fcommander/lists"}