{"id":15406783,"url":"https://github.com/dannyben/menu_commander","last_synced_at":"2025-07-10T12:16:01.485Z","repository":{"id":35169065,"uuid":"181165585","full_name":"DannyBen/menu_commander","owner":"DannyBen","description":"Create menus for any command line tool using simple YAML configuration","archived":false,"fork":false,"pushed_at":"2024-03-21T05:14:50.000Z","size":182,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-02T07:39:18.112Z","etag":null,"topics":["cli","cli-menu","gem","menu-builder","menu-generator","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/DannyBen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-04-13T12:09:30.000Z","updated_at":"2025-05-25T07:06:04.000Z","dependencies_parsed_at":"2024-10-19T12:33:32.377Z","dependency_job_id":"2e2087c2-747a-4f1b-a9bb-9ad8aba61e13","html_url":"https://github.com/DannyBen/menu_commander","commit_stats":{"total_commits":102,"total_committers":2,"mean_commits":51.0,"dds":"0.019607843137254943","last_synced_commit":"ea42a8936ae8754dec62324ea9b4663505c2bc02"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/DannyBen/menu_commander","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmenu_commander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmenu_commander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmenu_commander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmenu_commander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DannyBen","download_url":"https://codeload.github.com/DannyBen/menu_commander/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmenu_commander/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261094195,"owners_count":23108748,"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":["cli","cli-menu","gem","menu-builder","menu-generator","ruby"],"created_at":"2024-10-01T16:25:21.801Z","updated_at":"2025-07-10T12:16:01.439Z","avatar_url":"https://github.com/DannyBen.png","language":"Ruby","readme":"Menu Commander\n==================================================\n\n[![Gem Version](https://badge.fury.io/rb/menu_commander.svg)](https://badge.fury.io/rb/menu_commander)\n[![Build Status](https://github.com/DannyBen/menu_commander/workflows/Test/badge.svg)](https://github.com/DannyBen/menu_commander/actions?query=workflow%3ATest)\n[![Maintainability](https://api.codeclimate.com/v1/badges/aa048e0f2cf1655261ac/maintainability)](https://codeclimate.com/github/DannyBen/menu_commander/maintainability)\n\n---\n\nEasily create menus for any command line tool using simple YAML configuration.\n\n---\n\n![Demo](/demo/cast.svg)\n\n---\n\nInstallation\n--------------------------------------------------\n\n```shell\n$ gem install menu_commander\n```\n\n\nUsage\n--------------------------------------------------\n\nMenu Commander adds the `menu` command line tool to your path. When running \nit without arguments, it will look for a `menu.yml` file in the current \ndirectory, and will provide you with a menu to execute any shell command.\n\nA basic menu configuration file looks like this:\n\n```yaml\n# menu.yml\n\n# Using %{variables} in a command will prompt for an input when executed\nmenu:\n  hello: echo hello\n  hi: echo hi %{name}\n\n# Define sub menus for any %{variable} that was defined in the command\nargs:\n  name:\n  - Harry\n  - Lloyd\n```\n\nThen, start the menu by running:\n\n```shell\n# Start the menu with ./menu.yml\n$ menu\n\n# Start the menu with ./some-other-file.yml\n$ menu some-other-file\n```\n\n### Menu Navigation\n\n- When a menu or sub menu has more than 10 items, it will become paginated\n  and a search filter will be added.\n- Pressing \u003ckbd\u003eHome\u003c/kbd\u003e from any nested menu will go back to the first \n  menu.\n- Pressing \u003ckbd\u003ePage Up\u003c/kbd\u003e from any nested menu will go back to the \n  previous menu.\n- Pressing \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eC\u003c/kbd\u003e will exit from the menu.\n\n\n\nMenu Definition\n--------------------------------------------------\n\nAll features have an example configuration in the\n[examples folder](examples). To run an example, simply execute \n`menu EAXMPLE_NAME` form within the examples folder, where `EXAMPLE_NAME` \nis the name of the YAML file without the extension.\n\n### Minimal menu requirements\n\nThe only requirement for a minimal menu is to have a `menu` definition\nwith `key: command` to run.\n\n```yaml\nmenu:\n  hello: echo hello\n  whoami: whoami\n```\n\n\u003e See: [examples/minimal.yml](examples/minimal.yml)\n\n### Argument sub-menus\n\nUsing `%{variables}` in a command will prompt for an input when executed. The \nsub-menu for that input is specified in the `args` definition.\n\n```yaml\nmenu:\n  server: rails server --env %{environment}\n  test: RAILS_ENV=%{environment} rspec\n\nargs:\n  environment:\n    - staging\n    - production\n```\n\n\u003e See: [examples/args-array.yml](examples/args-array.yml)\n\nIn case the argument array contains only one array element for a given \nvariable, it will be automatically used without prompting the user.\n\nThis is useful when you need to define variables that repeat multiple times\nin your menu.\n\n```yaml\nargs:\n  server: [localhost]\n```\n\n\u003e See: [examples/args-static.yml](examples/args-static.yml)\n\nUsing `key: value` pairs in the `args` menu will create a sub-menu with \nlabels that are different from their substituted value:\n\n```yaml\nmenu: \n  server: rails server --env %{environment}\n  test: RAILS_ENV=%{environment} rspec\n\nargs:\n  environment:\n    Staging Environment: staging\n    Production Environment: production\n```\n\n\u003e See: [examples/args-hash.yml](examples/args-hash.yml)\n\nIn order to obtain the sub-menu items from a shell command, simply provide\nthe command to run, instead of providing the menu options. The command is\nexpected to provide newline-delimited output.\n\n```yaml\nmenu:\n  show: cat %{file}\n  edit: vi %{file}\n\nargs:\n  file: ls \n```\n\n\u003e See: [examples/args-shell.yml](examples/args-shell.yml)\n\n### Free text input\n\nWhen using a `%{variable}` that does not have a corresponding definition in\nthe `args` section, you will simply be prompted for a free text input:\n\n```yaml\nmenu:\n  release: \n    echo %{version} \u003e version.txt \u0026\u0026\n    git tag v%{version}\n```\n\n\u003e See: [examples/args-free-text.yml](examples/args-free-text.yml)\n\n### Nested menus\n\nYou can nest as many menu levels as you wish under the menu definition.\n\n```yaml\nmenu:\n  docker:\n    images: docker images ls\n    containers: docker ps -a\n    stack:\n      deploy: docker stack deploy -c docker-compose.yml mystack\n      list: docker stack ls\n\n  git:\n    status: git status\n    branch: git branch\n```\n\n\u003e See: [examples/args-nested.yml](examples/args-nested.yml)\n\n\n### Split menu into several files\n\nEach menu configuration file can include any number of additional YAML\nfiles inside it. This is useful when:\n\n- Your menu configuration file becomes too long, and you wish to split it\n  to separate logical units.\n- You have multiple menu files, and you want to include common configuration\n  in each of them.\n\nThis is done by using the `extends` option:\n\n```yaml\n# examples/extend.yml\nextends: extend-parent.yml\n\nmenu:\n  hello: echo hello\n  hi: echo hi %{name}\n\nargs:\n  name: [Harry, Lloyd]\n  server: [example.com]\n```\n\n\u003e See: [examples/extend.yml](examples/extend.yml)\n\nThe below configuration will be merged into the above menu:\n\n```yaml\n# examples/extend-parent.yml\nmenu:\n  ping: ping %{server}\n\nargs:\n  server: [localhost, google.com]\n```\n\n\u003e See: [examples/extend-parent.yml](examples/extend-parent.yml)\n\n\n### Multi-line commands\n\nProviding an array to a menu, will join the array with '\u0026\u0026' to a single\ncommand. Alternatively, you can use a simple YAML multi-line string.\n\n\n```yaml\nmenu:\n  deploy:\n    - run tests\n    - git commit -am \"automatic commit\"\n    - git push\n\n  alternative: \u003e\n    run tests \u0026\u0026\n    git commit -am \"automatic commit\" \u0026\u0026\n    git push\n```\n\n\u003e See: [examples/multiline.yml](examples/multiline.yml)\n\n\nMenu Options\n--------------------------------------------------\n\nYou can tweak several aspects of the menu by adding an `options` section\nin your YAML file.\n\n```yaml\n# Optional menu configuration\noptions:\n  # Show header text\n  header: Hello\n\n  # Marker to show as the suffix of items that have submenus\n  # Use false to disable\n  submenu_marker: \" ...\"\n\n  # Menu selection marker\n  select_marker: \"\u003e\"\n\n  # Menu title marker\n  title_marker: \"-\"\n\n  # When a menu has more items than page_size, add pagiation\n  # Default 10\n  page_size: 2\n\n  # When to show search filter\n  # yes      = always show\n  # no       = never show\n  # auto     = show only when there are more items than page_size (default)\n  # \u003cnumber\u003e = show only when there are more items than \u003cnumber\u003e\n  filter: yes\n\n  # When arg lists generate one item only it is auto-selected by default.\n  # Set this to false to disable this behavior\n  auto_select: false\n\n  # Show the command after execution\n  echo: true\n\n  # Marker to use when echoing the command and it was successful\n  echo_marker_success: \"==\u003e\"\n\n  # Marker to use when echoing the command and it failed\n  echo_marker_error: \"ERROR ==\u003e\"\n\n```\n\n\u003e See: [examples/options.yml](examples/options.yml)\n\n\n\nMenu File Location\n--------------------------------------------------\n\nBy default, menu files are looked for in the current working directory. \n\nYou may instruct Menu Commander to look in additional locations by setting\nthe `MENU_PATH` environment variable to one or more paths. Note that when\nusing this method, Menu Commander will *not* look in the current directory, \nunless you include it in `MENU_PATH`, like this:\n\n```shell\n$ export MENU_PATH=.:$HOME/menus:/etc/menus\n```\n\nIf you wish this setting to be permanent, add it to your `.bashrc` or your \npreferred initialization script.\n\n\n[1]: https://github.com/dannyben/colsole#color-codes\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fmenu_commander","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannyben%2Fmenu_commander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fmenu_commander/lists"}