# promised-ssh

> Promise wrapped ssh2

Latest version **0.6.2** (published 2017-04-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install promised-ssh
pnpm add promised-ssh
yarn add promised-ssh
bun add promised-ssh
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.2 |
| Published | 2017-04-21 |
| First published | 2015-03-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Rolf Erik Lekang |
| Maintainers | relekang |
| Keywords | promise, ssh, ssh2, promises |

## Links

- npm: https://www.npmjs.com/package/promised-ssh
- Repository: https://github.com/relekang/promised-ssh
- Issues: https://github.com/relekang/promised-ssh/issues
- npm.io page: https://npm.io/package/promised-ssh

## Dependencies (4)

- [ssh2](https://npm.io/package/ssh2.md) ^0.5.4
- [util](https://npm.io/package/util.md) ^0.10.3
- [utils](https://npm.io/package/utils.md) 0.0.2
- [bluebird](https://npm.io/package/bluebird.md) ^3.4.7

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 0.6.2 (latest) — 2017-04-21
- 0.6.1 — 2017-01-16
- 0.6.0 — 2016-03-10
- 0.5.0 — 2015-07-21
- 0.4.1 — 2015-05-15
- 0.4.0 — 2015-04-29
- 0.3.1 — 2015-04-24
- 0.3.0 — 2015-03-04
- 0.2.1 — 2015-03-04
- 0.2.0 — 2015-03-03
- 0.1.1 — 2015-03-01
- 0.1.0 — 2015-03-01

## README

# promised-ssh
Promise wrapped ssh2

## Install
```
npm install --save promised-ssh
```

## Usage
#### `.connect(options)`
Takes a object with options similar to ssh2. This object is passed along
to ssh2 connect. It returns a promise of an `Connection`.

#### `.connectMock(options)`
Returns a `MockConnection` which behaves similarly to `Connection` except
it never tries to connect anywhere and the outcome of commands and the mocked
connection is determined by mock-options which can be set with `.setMockOptions`.

#### `.setMockOptions(options)`
Sets the options used to determine the outcome of `MockConnection.connect` and
`MockConnection.exec`. It takes an object with options. The possible options are:

* `failConnect` (boolean) - Tells whether `MockConnection.connect` should fail or not.
  Default is `false`. If this is true it will throw an `ConnectionError` which is
  exposed under errors.
* `commands` (object) - An object with information about return code, stdout and
  stderr that a command should give. All three options is optional and have the
  following defaults: code=0, stdout='', stderr=''. The default for the option
  is `{}`
* `throwIfMockNotDefined` (boolean) - Throw an error if exec is called
  on a command that doesn't have a mock output defined

Example
```javascript
ssh.setMockOptions({
  commands: {
    'cd project && make': {
      stdout: 'make: Nothing to be done for `all`.'
    }
  }
})
```

#### `.setOfflineMode(true)`
Will prevent any real connections from being made, causing an error to
be throwin instead. Useful when in test mode to make sure tests don't
trigger connections to remote servers.

### Connection
#### `Connection.connect()`
Returns a promise that resolves a `Connection`-object when ssh2 opens a connection.
`this.options` is used as connect options in ssh2.

#### `Connection.exec(list_of_commands)`
Takes a list of commands to run on the current connection. After the commands
have been runned the connection will be closed. It returns a promise of an array:
`[stdout, stderr]`.

### Example
```javascript
var ssh = require('promised-ssh');

ssh
  .connect({
    host: 'localhost',
    username: 'rolf',
    privateKey: '...'
  })
  .then(function(connection) {
    return connection.exec(['ls -al']);
  })
  .spread(function(stdout, stderr) {
    console.log('Returned with return code ' + return_code);
    if (stdout) console.log('STDOUT: ' + stdout);
    if (stderr) console.log('STDERR: ' + stderr);
  })
  .catch(function(error) {
    // error is here an instance of ssh.errors.CommandExecutionError
    // it contains information about exit code, stdout and stderr
    throw error;
  });
```

---
_Source: https://npm.io/package/promised-ssh · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._