Vagrant DevCommands

Runs vagrant commands from a Commandfile.

Usage

Command Listing

vagrant run

Command Execution

# single-vm environment
# or multi-vm environment with :box option
vagrant run your_command

# multi-vm environment
vagrant run your_box your_command

Command Definition

Add to a Commandfile besides your Vagrantfile:

command 'basic', 'hostname'

command 'with_options',
    box: :my_box,
    desc: 'executes "hostname" on the box "my_box"',
    script: 'hostname',
    usage: 'vagrant run %{command}',
    help: <<-eoh
I am the help message for the command "with_options".
I get displayed when running "vagrant run help with_options".

The usage printed above the help can interpolate the name
of the command name using %{command}.
eoh

Note: If you are defining literal % (percent sign) in your commands you have to escape them using a second %. For example date "+%%Y-%%m-%%d".

Commands with Parameters

Passing additional parameters to a command is (minimally) supported using an sprintf syntax:

command 'with_param',
  parameters: {
    # mandatory parameter
    mdtry: {},
    # parameter with default (implies optional)
    dflt: { default: "always" },
    # optional parameter
    optnl: { optional: true },
    # wrapped option value
    wrppd: { wrap: "--and %s wrapped" }
  },
  script: 'echo %{mdtry} %{dflt} %{optnl} %{wrppd}'

This allows you to execute the following command:

# will execute 'echo works always'
vagrant run with_param --mdtry works

# will execute 'echo works always like a charm'
vagrant run with_param --mdtry works --optnl "like a charm"

# will execute 'echo works sometimes like a charm --and is wrapped'
vagrant run with_param \
    --mdtry works \
    --dflt sometimes \
    --optnl "like a charm" \
    --wrppd is

For now a command expecting one or more parameters will fail if the user does not provide them. Any arguments exceeding the number used are silently discarded.

Commands defined by Lambda/Proc

You can (more or less) dynamically generate your scripts by defining the command with a lambda or proc as its script.

command 'from_lambda', script: lambda { 'echo "lambda works"' }
command 'from_proc', script: proc { 'echo "proc works"' }

These will be evaluated when running the command.

Every rule from regular scripts (parameters, escaping "%", ...) still apply.

Experimental: global command definitions

To have commands available even wihout a Commandfile you can define the globally. To do this just create a file named .vagrant.devcommands in your $HOME directory.

You can use this command to find the correct path if unsure:

ruby -e "require 'pathname'; puts Pathname.new(Dir.home).join('.vagrant.devcommands')"

Any commands defined there will silently be overwritten by a local definition.

Abort parsing inside Commandfile

If you, for whatever reasons, want to abort further parsing of a Commandfile you can simple return from it:

command 'foo', script: 'foo'


v_cur = Gem::Version.new(VagrantPlugins::DevCommands::VERSION)
v_min = Gem::Version.new('1.3.3.7')

return if v_cur < v_min


command 'bar', script: 'bar'

This example leads to the command bar not being available if the currently installed plugin has a version below 1.3.3.7.

Please be aware that returning from a global commandfile completely skips evaluating a local one.

Notes for Windows Users

SSH

If you are using this plugin on a Windows host system, please make sure your regular vagrant ssh [box] succeeds. In some cases you may need to add the ssh.exe (i.e. from a git installation) manually to your %PATH%.

Command Definition

When using multi-line commands you probably need to define your command using a sigil notation like the following:

command 'long_running_task',
    script: %(cd /path/to/somewhere \
                  && echo "starting long running task" \
                  && ./long_running_task.sh \
                  && echo "finished long running task")

Using a quote delimited command definition might otherwise result in not that helpful error messages about a bad shell command.

It might also help to double check the line endings in your Commandfile are set unix-style (\n) and not windows-style (\r\n) if you get errors when running your commands.

License

Licensed under the MIT license.