elevator/README.md

Windows UAC elevation that just works

elevator
========

> Windows UAC elevation that just works.

[![npm version](https://badge.fury.io/js/elevator.svg)](http://badge.fury.io/js/elevator)
[![dependencies](https://david-dm.org/resin-io-modules/elevator.svg)](https://david-dm.org/resin-io-modules/elevator.svg)
[![Build status](https://ci.appveyor.com/api/projects/status/ysweh6h4ed4ak114/branch/master?svg=true)](https://ci.appveyor.com/project/resin-io/elevator/branch/master)
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/resin-io/chat)

Description
-----------

This module is a thin wrapper around the awesome [elevate.exe utility by kliu](http://code.kliu.org/misc/elevate/), which is a small C open source application with x64 and ia32 support that just works.

This module doesn't make use of NodeJS C/C++ bindings and instead relies on executing the `.exe` file direcly in a way that is [electron](http://electron.atom.io) friendly even when the application is packaged in an `asar` archive.

Of course, this means that this NodeJS module is subjected to the Windows versions and architectures such supports. Windows Vista (or newer) is required.

Installation
------------

Install `elevator` by running:

```sh
$ npm install --save elevator
```

Documentation
-------------


* [elevator](#module_elevator)
    * [.execute(command, [options], callback)](#module_elevator.execute)
    * [.executeSync(command, [options])](#module_elevator.executeSync) ⇒ <code>String</code>

<a name="module_elevator.execute"></a>

### elevator.execute(command, [options], callback)
This function will yield an `Error` containing a code that equals
`ELEVATE_CANCELLED` if the elevation was cancelled by the user.

**Kind**: static method of <code>[elevator](#module_elevator)</code>  
**Summary**: Execute a command with UAC elevation  
**Access:** public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| command | <code>Array.&lt;String&gt;</code> |  | command |
| [options] | <code>Object</code> | <code>{}</code> | options |
| [options.terminating] | <code>Boolean</code> |  | Launches a terminating command processor; equivalent to "cmd /c command". |
| [options.persistent] | <code>Boolean</code> |  | Launches a persistent command processor; equivalent to "cmd /k command". |
| [options.doNotPushdCurrentDirectory] | <code>Boolean</code> |  | When using -c or -k, do not pushd the current directory before execution. |
| [options.unicode] | <code>Boolean</code> |  | When using -c or -k, use Unicode; equivalent to "cmd /u". |
| [options.hidden] | <code>Boolean</code> |  | When using -c or -k, start "cmd" in hidden mode. |
| [options.waitForTermination] | <code>Boolean</code> |  | Waits for termination; equivalent to "start /wait command". |
| callback | <code>function</code> |  | callback (error, stdout, stderr) |

**Example**  
```js
elevator.execute([ 'cmd.exe' ], {
  waitForTermination: true
}, function(error, stdout, stderr) {
  if (error) {
    throw error;
  }

  console.log(stdout);
  console.log(stderr);
});
```
<a name="module_elevator.executeSync"></a>

### elevator.executeSync(command, [options]) ⇒ <code>String</code>
This function will throw an `Error` containing a code that equals
`ELEVATE_CANCELLED` if the elevation was cancelled by the user.

**Kind**: static method of <code>[elevator](#module_elevator)</code>  
**Summary**: Execute a command with UAC elevation (Sync)  
**Returns**: <code>String</code> - stdout buffer  
**Access:** public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| command | <code>Array.&lt;String&gt;</code> |  | command |
| [options] | <code>Object</code> | <code>{}</code> | options |
| [options.terminating] | <code>Boolean</code> |  | Launches a terminating command processor; equivalent to "cmd /c command". |
| [options.persistent] | <code>Boolean</code> |  | Launches a persistent command processor; equivalent to "cmd /k command". |
| [options.doNotPushdCurrentDirectory] | <code>Boolean</code> |  | When using -c or -k, do not pushd the current directory before execution. |
| [options.unicode] | <code>Boolean</code> |  | When using -c or -k, use Unicode; equivalent to "cmd /u". |
| [options.hidden] | <code>Boolean</code> |  | When using -c or -k, start "cmd" in hidden mode. |
| [options.waitForTermination] | <code>Boolean</code> |  | Waits for termination; equivalent to "start /wait command". |

**Example**  
```js
elevator.executeSync([ 'cmd.exe' ], {
  waitForTermination: true
});
```

Support
-------

If you're having any problem, please [raise an issue](https://github.com/resin-io-modules/elevator/issues/new) on GitHub and the Resin.io team will be happy to help.

Tests
-----

Run the test suite by doing:

```sh
$ gulp test
```

Contribute
----------

- Issue Tracker: [github.com/resin-io-modules/elevator/issues](https://github.com/resin-io-modules/elevator/issues)
- Source Code: [github.com/resin-io-modules/elevator](https://github.com/resin-io-modules/elevator)

Before submitting a PR, please make sure that you include tests, and that [jshint](http://jshint.com) runs without any warning:

```sh
$ gulp lint
```

License
-------

The project is licensed under the MIT license.