# heroku-cli-util

> Set of helpful CLI utilities

Latest version **8.0.12** (published 2019-12-18) · ISC license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install heroku-cli-util
pnpm add heroku-cli-util
yarn add heroku-cli-util
bun add heroku-cli-util
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 8.0.12 |
| Published | 2019-12-18 |
| First published | 2014-12-03 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 6.0.0 |
| Dependencies | 15 |
| Unpacked size | 83.8 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 43 |
| Author | Jeff Dickey |
| Maintainers | dhaulagiri, dickeyxxx, elbandito, itops, rasphilco |

## Links

- npm: https://www.npmjs.com/package/heroku-cli-util
- Repository: https://github.com/heroku/heroku-cli-util
- Issues: https://github.com/heroku/heroku-cli-util/issues
- npm.io page: https://npm.io/package/heroku-cli-util

## Dependencies (15)

- [co](https://npm.io/package/co.md) ^4.6.0
- [got](https://npm.io/package/got.md) ^8.3.1
- [opn](https://npm.io/package/opn.md) ^3.0.3
- [chalk](https://npm.io/package/chalk.md) ^2.4.1
- [tslib](https://npm.io/package/tslib.md) ^1.9.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.10
- [cardinal](https://npm.io/package/cardinal.md) ^2.0.1
- [strip-ansi](https://npm.io/package/strip-ansi.md) ^4.0.0
- [ansi-styles](https://npm.io/package/ansi-styles.md) ^3.2.1
- [ansi-escapes](https://npm.io/package/ansi-escapes.md) ^3.1.0
- [netrc-parser](https://npm.io/package/netrc-parser.md) ^3.1.4
- [tunnel-agent](https://npm.io/package/tunnel-agent.md) ^0.6.0
- [heroku-client](https://npm.io/package/heroku-client.md) ^3.1.0
- [supports-color](https://npm.io/package/supports-color.md) ^5.4.0
- [@heroku-cli/color](https://npm.io/package/@heroku-cli/color.md) ^1.1.3

## Recent versions

- 8.0.12 (latest) — 2019-12-18
- 8.0.11 — 2018-12-13
- 8.0.10 — 2018-08-22
- 8.0.9 — 2018-05-10
- 8.0.8 — 2018-05-07
- 8.0.7 — 2018-05-06
- 8.0.6 — 2018-04-16
- 8.0.5 — 2018-04-10
- 8.0.4 — 2018-04-06
- 8.0.3 — 2018-04-02
- 8.0.2 — 2018-03-29
- 8.0.1 — 2018-03-19
- 8.0.0 — 2018-02-07
- 6.2.13 — 2018-02-01
- 7.0.2 — 2018-02-01
- … 140 more at https://npm.io/package/heroku-cli-util/versions

## README

# heroku-cli-util [![Circle CI](https://circleci.com/gh/heroku/heroku-cli-util/tree/master.svg?style=svg)](https://circleci.com/gh/heroku/heroku-cli-util/tree/master)

[![Code Climate](https://codeclimate.com/github/heroku/heroku-cli-util/badges/gpa.svg)](https://codeclimate.com/github/heroku/heroku-cli-util)
[![Test Coverage](https://codeclimate.com/github/heroku/heroku-cli-util/badges/coverage.svg)](https://codeclimate.com/github/heroku/heroku-cli-util/coverage)
[![npm version](https://badge.fury.io/js/heroku-cli-util.svg)](http://badge.fury.io/js/heroku-cli-util)
[![License](https://img.shields.io/github/license/heroku/heroku-cli-util.svg)](https://github.com/heroku/heroku-cli-util/blob/master/LICENSE)

Set of helpful CLI utilities

## Installation

```sh
npm install heroku-cli-util --save
```

## Action

```js
let cli = require('heroku-cli-util');
yield cli.action('restarting dynos', co(function* () {
  let app = yield heroku.get(`/apps/${context.app}`);
  yield heroku.request({method: 'DELETE', path: `/apps/${app.name}/dynos`});
}));

// restarting dynos... done
```

## Prompt

```js
let cli   = require('heroku-cli-util');
let email = yield cli.prompt('email', {});
console.log(`your email is: ${email}`);
```

**cli.prompt options**

```js
cli.prompt('email', {
  mask: true, // mask input field after submitting
  hide: true // mask characters while entering
});
```

## Confirm App

Supports the same async styles as `prompt()`. Errors if not confirmed.

Basic

```js
let cli = require('heroku-cli-util');
yield cli.confirmApp('appname', context.flags.confirm);

// !     WARNING: Destructive Action
// !     This command will affect the app appname
// !     To proceed, type appname or re-run this command with --confirm appname

> appname
```

Custom message

```js
let cli = require('heroku-cli-util');
yield cli.confirmApp('appname', context.flags.confirm, 'foo');

// !     foo
// !     To proceed, type appname or re-run this command with --confirm appname

> appname
```

Note that you will still need to define a `confirm` flag for your command.

## Errors

```js
let cli = require('heroku-cli-util');
cli.error("App not found");
// !    App not found
```

## Warnings

```js
let cli = require('heroku-cli-util');
cli.warn("App not found");
// !    App not found
```

## Dates

```js
let cli = require('heroku-cli-util');
let d   = new Date();
console.log(cli.formatDate(d));
// 2001-01-01T08:00:00.000Z
```

## Hush

Use hush for verbose logging when `HEROKU_DEBUG=1`.

```js
let cli = require('heroku-cli-util');
cli.hush('foo');
// only prints if HEROKU_DEBUG is set
```

## Debug

Pretty print an object.

```js
let cli = require('heroku-cli-util');
cli.debug({foo: [1,2,3]});
// { foo: [ 1, 2, 3 ] }
```

## Stylized output

Pretty print a header, hash, and JSON
```js
let cli = require('heroku-cli-util');
cli.styledHeader("MyApp");
cli.styledHash({name: "myapp", collaborators: ["user1@example.com", "user2@example.com"]});
cli.styledJSON({name: "myapp"});
```

Produces

```
=== MyApp
Collaborators: user1@example.com
               user1@example.com
Name:          myapp

{
  "name": "myapp"
}
```

## Table

```js
cli.table([
  {app: 'first-app',  language: 'ruby', dyno_count: 3},
  {app: 'second-app', language: 'node', dyno_count: 2},
], {
  columns: [
    {key: 'app'},
    {key: 'dyno_count', label: 'Dyno Count'},
    {key: 'language', format: language => cli.color.red(language)},
  ]
});
```

Produces:

```
app         Dyno Count  language
──────────  ──────────  ────────
first-app   3           ruby
second-app  2           node
```

## Linewrap

Used to indent output with wrapping around words:

```js
cli.log(cli.linewrap(2, 10, 'this is text is longer than 10 characters'));
// Outputs:
//
// this
// text is
//  longer
//  than 10
//  characters`);
```

Useful with `process.stdout.columns || 80`.

## Open Web Browser

```js
yield cli.open('https://github.com');
```

## HTTP calls

`heroku-cli-util` includes an instance of [got](https://www.npmjs.com/package/got) that will correctly use HTTP proxies.

```js
let cli = require('heroku-cli-util');
let rsp = yield cli.got('https://google.com');
```

## Mocking

Mock stdout and stderr by using `cli.log()` and `cli.error()`.

```js
let cli = require('heroku-cli-util');
cli.log('message 1'); // prints 'message 1'
cli.mockConsole();
cli.log('message 2'); // prints nothing
cli.stdout.should.eq('message 2\n');
```

## Command

Used for initializing a plugin command.
give you an auth'ed instance of `heroku-client` and cleanly handle API exceptions.

It expects you to return a promise chain. This is usually done with [co](https://github.com/tj/co).

```js
let cli = require('heroku-cli-util');
let co  = require('co');
module.exports.commands = [
  {
    topic: 'apps',
    command: 'info',
    needsAuth: true,
    needsApp: true,
    run: cli.command(function (context, heroku) {
      return co(function* () {
        let app = yield heroku.get(`/apps/${context.app}`);
        console.dir(app);
      });
    })
  }
];
```

With options:

```js
let cli = require('heroku-cli-util');
let co  = require('co');
module.exports.commands = [
  {
    topic: 'apps',
    command: 'info',
    needsAuth: true,
    needsApp: true,
    run: cli.command(
      {preauth: true},
      function (context, heroku) {
        return co(function* () {
          let app = yield heroku.get(`/apps/${context.app}`);
          console.dir(app);
        });
      }
    )
  }
];
```

If the command has a `two_factor` API error, it will ask the user for a 2fa code and retry.
If you set `preauth: true` it will preauth against the current app instead of just setting the header on an app. (This is necessary if you need to do more than 1 API call that will require 2fa)

## Tests

```sh
npm install
npm test
```

## License

ISC

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