{"id":16410690,"url":"https://github.com/justim/consoler-rb","last_synced_at":"2026-02-12T06:32:30.323Z","repository":{"id":55443669,"uuid":"124266869","full_name":"justim/consoler-rb","owner":"justim","description":"Sinatra-like application builder for the console","archived":false,"fork":false,"pushed_at":"2025-02-11T13:48:31.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-30T16:12:25.667Z","etag":null,"topics":["console","console-framework","gem","ruby"],"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/justim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-03-07T16:56:03.000Z","updated_at":"2025-02-11T13:48:00.000Z","dependencies_parsed_at":"2024-10-28T15:27:28.195Z","dependency_job_id":"6cf60f5a-690d-4fd3-8514-54fc2e8f3651","html_url":"https://github.com/justim/consoler-rb","commit_stats":{"total_commits":42,"total_committers":2,"mean_commits":21.0,"dds":"0.023809523809523836","last_synced_commit":"7c8f879d064c625be4a73271bc2507194ccf05b3"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/justim/consoler-rb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justim%2Fconsoler-rb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justim%2Fconsoler-rb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justim%2Fconsoler-rb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justim%2Fconsoler-rb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justim","download_url":"https://codeload.github.com/justim/consoler-rb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justim%2Fconsoler-rb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29360644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"online","status_checked_at":"2026-02-12T02:00:06.911Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["console","console-framework","gem","ruby"],"created_at":"2024-10-11T06:43:39.349Z","updated_at":"2026-02-12T06:32:30.308Z","avatar_url":"https://github.com/justim.png","language":"Ruby","readme":"# Consoler [![Gem Version](https://badge.fury.io/rb/consoler.svg)](https://badge.fury.io/rb/consoler)\n\n\u003e Sinatra-like application builder for the console\n\n## Quick usage\n\n```ruby\n# create an application\napp = Consoler::Application.new description: 'A simple app'\n\n# define a command\napp.build '[--clean] \u003coutput_dir\u003e' do |clean, output_dir|\n  # clean contains a boolean\n  clean_up if clean\n\n  # output_dir contains a string\n  build_project output_dir\nend\n\n# run with own args\napp.run ['build', 'production', '--clean']\n\n# this does not match, nothing is executed and the usage message is printed\napp.run ['deploy', 'production']\n\n# defaults to ARGV\napp.run\n```\n\n## Features\n\n- No fiddling with `ARGV` and friends\n- Arguments filled based on their name, for easy access\n- Grouped optionals\n- Easy option aliasing\n\n## Requirements\n\nTests are run against multiple ruby versions (latest supported):\n\n- `2.4.x`\n- `2.5.x`\n- `2.6.x`\n- `2.7.x`\n- `3.0.x`\n\nNo other requirements exist.\n\n## Installation\n\n```sh\ngem install consoler\n```\n\nor add to your `Gemfile` for applications\n\n```ruby\ngem 'consoler', '~\u003e 1.3.0'\n```\n\nor to your `.gemspec` file for gems\n\n```ruby\nGem::Specification.new do |spec|\n  spec.add_dependency 'consoler', '~\u003e 1.3.0'\nend\n```\n\n## Docs\n\nFull API documentation can the found here: https://www.rubydoc.info/gems/consoler/1.3.0\n\n### API\n\n#### Creating an application\n\n```ruby\n# create an application\napp = Consoler::Application.new\n\n# .. or with a description that will show up in the usage message\napp = Consoler::Application.new description: 'A simple app'\n```\n\n#### Adding commands\n\nAll actions you want to create must have a command name, there is no top-level matching available at this point.\n\n```ruby\n# create an application\napp = Consoler::Application.new\n\n# in the most simple way, you provide a name (the method name) and a block you\n# want to execute if it matches\napp.build do\n  # your code here\nend\n\n# to add options to your command, provide a options definition as an argument\napp.build '[--clean] [--env=] [-v|--verbose] \u003coutput_dir\u003e' do |clean, env, verbose, output_dir|\n  # parameters are matched based on name\n  # `clean` contains a boolean\n  # `env` contains a string or nil if not provided\n  # `verbose` contains a number, counting the times it occurred in the arguments\n  # `output_dir` contains a string, if needed to match this command\nend\n```\n\n#### Running the application\n\n```ruby\n# filename: app.rb\n\n# create an application\napp = Consoler::Application.new\n\n# a build command\napp.build '[--clean] [--env=] [-v|--verbose] \u003coutput_dir\u003e' do |clean, env, verbose, output_dir|\n  puts 'Starting build...' if verbose \u003e 0\n\n  do_clean_up if clean\n\n  do_build env || 'development', output_dir\n\n  puts 'Build complete' if verbose \u003e 0\nend\n\n# a deploy command\napp.build '[-v|--verbose] [--env=]' do |env|\n  puts 'Starting deploy...' if verbose \u003e 0\n\n  do_deploy env || 'development'\n\n  puts 'Deploy complete' if verbose \u003e 0\nend\n```\n\n_Shell commands:_\n```sh\n# start a build\nruby app.rb build --env production dist\n\n# deploy\nruby app.rb deploy --verbose\n\n# or, you can use command shortcuts. this works by prefix matching and only if\n# there is one match, exact matches always have priority\nruby app.rb b --env production dist\nruby app.rb d --verbose\n\n```\n\n#### Options definition\n\n| Option          | Meaning                         | Example                                |\n| --------------- | ------------------------------- | -------------------------------------- |\n| `-f`            | Short option with name `f`      | `ruby app.rb build -f`                 |\n| `--clean`       | Long option with name `clean`   | `ruby app.rb build --clean`            |\n| `-v\\|--verbose` | Alias option for `v`            | `ruby app.rb build --verbose`          |\n| `\u003coutput_dir\u003e`  | Argument with name `output_dir` | `ruby app.rb build dist/`              |\n| `--env=`        | Long option with value          | `ruby app.rb build --env production`   |\n| `-e=`           | Short option with value         | `ruby app.rb build -e production`      |\n| `[ .. ]`        | Optional options/arguments      | `ruby app.rb build` would match `[-v]` |\n\nSome notes about these options:\n\n- The `\u003c`, `\u003e` around the argument name a optional, but are always shown in de usage message for better legibility\n- Optional-tokens can occur anywhere in the options, as long as they are not nested and properly closed. You can group optional parts, meaning that both options/arguments should be available or both not.\n- Options and/or arguments are mandatory unless specified otherwise.\n- Aliases should be the same \"type\", meaning that if the original option expands an value, the alias must do as well\n- Aliases are only allowed for short and long options, with or without value and can be optional, just like regular options\n\nGrouping of optionals allows you do things like this:\n\n```ruby\napp = Consoler::Application.new\napp.shout '[\u003cfirst_name\u003e \u003clast_name\u003e] [\u003cname\u003e]' do |first_name, last_name, name|\n  # by definition, `last_name` is also filled\n  unless first_name.nil? then\n    puts \"Hello #{first_name} #{last_name}!\"\n  end\n\n  unless name.nil? then\n    puts \"Hello #{name}!\"\n  end\nend\n\n# calling with two arguments can fill the first group\n# prints \"Hello John Doe!\"\napp.run ['shout', 'John', 'Doe']\n\n# calling with one argument it is not possible to fill the first group\n# prints \"Hello Mr. White!\"\napp.run ['shout', 'Mr. White!']\n```\n\n#### Return types in action block\n\n| Option type | Return type (ex.)       | Default (if optional) |\n| ----------- | ----------------------- | --------------------- |\n| Short       | `Integer` (`1`)         | `0`                   |\n| Long        | `Boolean` (`true`)      | `false`               |\n| Value       | `String` (`production`) | `nil`                 |\n| Argument    | `String` (`dist/`)      | `nil`                 |\n\nAliased keep the properties as the original options; with a definition of `-v|--verbose` and providing `--verbose` as an argument, both `v` and `verbose` contain a number (`1` in this case). Same goes the other way around; with a definition of `--force|-f` and providing `-f` as an argument, both `force` and `f` contain a boolean (`true` in this case).\n\n#### Subapplications\n\nTo make application nesting possible you can provide a complete application to a command, instead of an action block.\n\n```ruby\n# filename: app.rb\n\n# create a subapplication\nandroid = Consoler::Application.new\nandroid.build do; end\n\n# options are supported just like regular apps\nandroid.clean '--force|-f' do; end\n\n# create an application\napp = Consoler::Application.new\n\n# mount the android application on top of the android command\n# note that the command does not support options\napp.android android\n```\n\nYou can now run the next bit to run the android build command:\n\n```sh\nruby app.rb android build\n```\n\nYou can build them as complicated as you like :)\n\n### Complete example\n\n```ruby\n#!/usr/bin/env ruby\n\ndb = Consoler::Application.new\ndb.migrate '-- run all pending migrations' do\n  run_migrate\nend\n\ndb.rollback '[--migrations=] -- rollback a number of migrations' do |migrations|\n  run_rollback migrations || 1\nend\n\ncache = Consoler::Application.new\ncache.clear '[--env=] -- clear the cache for a given environment' do |env|\n  run_cache_clear env || 'development'\nend\n\ncache.warmup '[--env=] -- warmup the cache for a given environment' do |env|\n  run_cache_warmup env || 'development'\nend\n\napp = Consoler::Application.new\napp.db db\napp.cache cache\n\napp.build '[--clean] [--env=] [-v] \u003coutput_dir\u003e -- build the project' do |clean, env, v, output_dir|\n  puts 'Starting build...' if v \u003e 0\n\n  if clean\n    puts 'Starting clean...' if v \u003e 1\n    do_clean_up if clean\n  end\n\n  do_build env || 'development', output_dir\n\n  puts 'Build complete' if v \u003e 0\nend\n```\n\nMake the file executable with `chmod a+x app.rb`, you can now call it with `./app.rb` without `ruby` in front of it, saves a couple keystrokes.\n\n```sh\n# run all migration\n./app.rb db migrate\n# rollback the last 4 migrations\n./app.rb db rollback 4\n# clean production cache\n./app.rb cache clear --env production\n# build the project, including cleaning and logging\n./app.rb build --clean --env production -vv dist/\n# print the usage message\n./app.rb\n```\n\n## Final notes\n\nIf you like what you see, feel free to use it anyway you like. Also, don't hold back if you have suggestions/question and create an issue to let me know, and we can talk about it. And if you don't like what you see, PRs are welcome. You should probably file an issue first to make sure it's something worth doing, and the right way to do it.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustim%2Fconsoler-rb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustim%2Fconsoler-rb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustim%2Fconsoler-rb/lists"}