Skip to content
Create menus for any command line tool using simple YAML configuration
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
demo
examples
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE
README.md
Runfile
menu_commander.gemspec

README.md

Menu Commander

Gem Version Build Status Maintainability


Easily create menus for any command line tool using simple YAML configuration.


Installation

$ gem install menu_commander

Usage

Menu Commander adds the menu command line tool to your path. When running it without arguments, it will look for a menu.yml file in the current directory, and will provide you with a menu to execute any shell command.

A basic menu configuration file looks like this:

# menu.yml

# Using %{variables} in a command will prompt for an input when executed
menu:
  hello: echo hello
  hi: echo hi %{name}

# Define sub menus for any %{variable} that was defined in the command
args:
  name:
  - Harry
  - Lloyd

Running it, looks like this:

Demo

Menu Configuration Features

All features have an example configuration in the examples folder. To run an example, simply execute menu EAXMPLE_NAME form within the examples folder, where EXAMPLE_NAME is the name of the YAML file without the extension.

Minimal menu requirements

The only requirement for a minimal menu is to have a menu definition with key: command to run.

# examples/minimal.yml
menu:
  hello: echo hello
  whoami: whoami

Argument sub-menus

Using %{variables} in a command will prompt for an input when executed. The sub-menu for that input is specified in the args definition.

# examples/args-array.yml
menu:
  server: rails server --env %{environment}
  test: RAILS_ENV=%{environment} rspec

args:
  environment:
    - staging
    - production

Using key: value pairs in the args menu will create a sub-menu with labels that are different from their substituted value:

# examples/args-hash.yml
menu: 
  server: rails server --env %{environment}
  test: RAILS_ENV=%{environment} rspec

args:
  environment:
    Staging Environment: staging
    Production Environment: production

In order to obtain the sub-menu items from a shell command, simply provide the command to run, instead of providing the menu options. The command is expected to provide newline-delimited output.

# examples/args-shell.yml
menu:
  show: cat %{file}
  edit: vi %{file}

args:
  file: ls 

Free text input

When using a %{variable} that does not have a corresponding definition in the args section, you will simply be prompted for a free text input:

# examples/args-free-text.yml
menu:
  release: 
    echo %{version} > version.txt &&
    git tag v%{version}

Nested menus

You can nest as many menu levels as you wish under the menu definition.

# examples/nested.yml
menu:
  docker:
    images: docker images ls
    containers: docker ps -a
    stack:
      deploy: docker stack deploy -c docker-compose.yml mystack
      list: docker stack ls

  git:
    status: git status
    branch: git branch

Multi-line commands

Providing an array to a menu, will join the array with '&&' to a single command. Alternatively, you can use a simple YAML multi-line string.

# examples/multiline.yml
menu:
  deploy:
    - run tests
    - git commit -am "automatic commit"
    - git push

  alternative: >
    run tests &&
    git commit -am "automatic commit" &&
    git push

Menu File Location

By default, menu files are looked for in the current working directory.

You may instruct Menu Commander to look in additional locations by setting the MENU_PATH environment variable to one or more paths. Note that when using this method, Menu Commander will not look in the current directory, unless you include it in MENU_PATH, like this:

$ export MENU_PATH=.:$HOME/menus:/etc/menus

If you wish this setting to be permanent, add it to your .bashrc or your preferred initialization script.

You can’t perform that action at this time.