node-vagrant

Node js wrapper for vagrant CLI - command line tool.

This is light wrapper around vagrant CLI.
It uses spawn process, and every command requiring user input
such as init and destroy is created with switch —force or -f.

Installation

$ npm install node-vagrant --save

Usage

All callbacks are node style:

function(err, out)

where err is stderr if exit code != 0 and out is stdout if exit code == 0

Other commands

// import vagrant
var vagrant = require('node-vagrant');
// view version
vagrant.version(function(err, out) {});
// or --version ; out = { status: '2.0.3', major: 2, minor: 0, patch: 3 }
vagrant.versionStatus(function(err, out) {});
// view global status
// you can specify '--prune' as additional argument. By default global-status is based on a cache,
// prune removes invalid entries from the list.
// Note that this is much more time consuming than simply listing the entries.
vagrant.globalStatus(function(err, out) {});
vagrant.globalStatus('--prune', function(err, out) {});
// vagrant machine
// create machine - does not run command or init machine
// you can specify directory where Vagrantfile will be located
// and machine instanced
var machine = vagrant.create({ cwd: <String>, env: <Object> }) // cwd and env default to process' values
// init machine
// you can specify additional arguments by using array (applicable to other functions)
machine.init('ubuntu/trusty64', function(err, out) {});
machine.init(['ubuntu/trusty64'], function(err, out) {});
// -f is set by default
machine.init(['ubuntu/trusty64', '-f'], function(err, out) {});
// up
machine.up(function(err, out) {})
// status
machine.status(function(err, out) {});
// get ssh config - useful to retrieve private and connect to machine with ssh2
// out is an array of objects [{}] with properties: port, hostname, user, private_key
machine.sshConfig(function(err, out) {});
// execute an ssh command on the machine
machine.on('ssh-out', console.log);
machine.on('ssh-err', console.error);
machine.sshCommand('echo "a bash command"');
// provision
machine.provision(function(err, out) {});
// suspend
machine.suspend(function(err, out) {});
// resume
machine.resume(function(err, out) {});
// reload
machine.reload(function(err, out) {});
// halt
machine.halt(function(err, out) {});
// destroy
// uses -f by default
machine.destroy(function(err, out) {});
// snapshots
// push, pop, save, delete, restore, list and a snapshot() function.
// example:
machine.snapshots().push(cb);
// box repackage
// must be specific to a vagrant environment hence location in machine
machine.boxRepackage(name, provider, version, function(err, out) {})
// plugins
// expunge, install, uninstall, repair, update, list and a plugin() function.
// example:
machine.plugin().expunge(args, cb);
// DEPRECATED! For backward compatibility only
machine.pluginUpdate(function(err, out) {});
machine.pluginRepair(function(err, out) {});
// boxes
// box add
// uses -f by default
// depending on type of box provided (name,address,file,json) missing information may be prompted.
// please ensure that your add metheod is specific.
vagrant.boxAdd(box, args, function(err, out) {})
    .on('progress', function(out) {});
// box list
// out is an array of objects [{}] with properties: name, provider, version
vagrant.boxList(args, function(err, out) {});
// box outdated
// --global is used by default
// out is an array of objects [{}] with properties: name, status, currentVersion, latestVersion
// status can be 'up to date' 'out of date' 'unknown'
// if status is unknown currentVersion and latestVersion will be null
vagrant.boxOutdated(args, function(err, out) {});
// box prune
// uses -f by defaultprune
vagrant.boxPrune(args, function(err, out) {});
// box remove
// uses -f by default
vagrant.boxRemove(name, args, function(err, out) {});
// box repackage
// avalible in machine
// box update
// uses the --box and --provider flags by default
// provider can be null and in that case no --provider arg is added
vagrant.boxUpdate(box, provider, function(err, out) {});
    .on('progress', function(out) {});
// args
// should be array of args or a string for single flag see --prune abov
// ie
vagrant.boxAdd('ubuntu/trusty64', ['--clean', '--provider', 'virtualbox'], function(err, out) {})
//or simply
vagrant.boxAdd('ubuntu/trusty64', '--clean', function(err, out) {})

Events

.on('up-progress', function(out) {}); // receive stdout progress from up of vagrant
.on('progress', function(out) {}); // receive stdout box download progress

Receive any stdout/stderr output from a child subprocess. These work only on a Machine instance:

machine.on('stdout', function(data) {}); // data is a Buffer
machine.on('stderr', function(data) {}); // data is a Buffer

Example

Example script of a usage is in example/example.js

$ npm run example

Flags & env vars

Debug the commands sent to vagrant:

$ NODE_DEBUG=1 node example.js
node-vagrant command: [ 'global-status' ]
node-vagrant command: [ 'version' ]

Disable the debug:

$ NODE_DEBUG=1 NODE_VAGRANT_DISABLE_DEBUG=1 node example.js

Custom vagrant location:

$ VAGRANT_DIR=/custom/path node example.js

Promises

var vagrant = require('../index');
vagrant.promisify();
vagrant.init('ubuntu/trusty64').then(successCb, errorCb);

TODO

• multi-machine
• more detail vagrant file settings
  • firewall
  • networking
• boxing
• provisoning
• providers
• (native) promises (if available)
• use ES6 (after which will become version 2.x.x)