# nscm - the CLI Utility for [NodeSource Certified Modules](https://nodesource.com/products/certified-modules)

`nscm` is a simple utility for [NodeSource Certified Modules](https://nodesource.com/products/certified-modules) that can be used to easily authenticate with your Certified Modules registry, to whitelist pacakges that fail certification, and to generate a detailed report about current project and the modules it depends on.

## Installation

You can install it from `npm` by running:

```
$ npm install -g nscm
```

## Usage

This tool is meant to be used in the root folder of an application where the `package.json` file exists.

```
  Usage: nscm [command] [options]

  Commands:

    config, c           Configure nscm options
    help                Display help
    report, r           Get a report of your packages
    signin, s, login    Sign in to nscm
    signout, o, logout  Sign out of nscm
    verify              Verify if all packages are certified
    whitelist, w        Whitelist your packages

  Options:

    -C, --certified        Shows only certified packages
    -c, --concurrency <n>  Concurrency of requests (defaults to 15)
    -d, --dot              Formats the report in Graphiz dot (disabled by default)
    -f, --failed           Shows only packages that failed certification (disabled by default)
    -g, --github           Sign in using GitHub SSO (disabled by default)
    -G, --google           Sign in using Google SSO (disabled by default)
    -h, --help             Output usage information
    -j, --json             Formats the report in JSON (disabled by default)
    -o, --output           Save report to file (disabled by default)
    -p, --production       Only check production (disabled by default)
    -r, --registry         Certified modules registry (defaults to "")
    -s, --svg              Formats the report in SVG (disabled by default)
    -t, --token            Token for registry authentication (defaults to "")
    -v, --version          Output the version number

  Additional Help

    Add -h to the 'config' or 'whitelist' commands for additional help concerning those commands.

    nscm config -h
    nscm whitelist -h
```

## `nscm report` (default)

Returns a report of matching certified packages and their certification scores.

```
$ nscm report
please wait while we process the information
┌────────────────────────────────────┬───────────────┬────────┐
│ Package                            │ Version       │ Score  │
├────────────────────────────────────┼───────────────┼────────┤
│ body-parser                        │ 1.15.2        │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ debug                              │ 2.2.0         │ 70     │
├────────────────────────────────────┼───────────────┼────────┤
│ ms                                 │ 0.7.1         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ bytes                              │ 2.4.0         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ content-type                       │ 1.0.2         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ depd                               │ 1.1.0         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ http-errors                        │ 1.5.1         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ inherits                           │ 2.0.3         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
```

You can also pass `--json` to return the report in JSON format,
`--svg` to return the report in SVG format, or
`--dot` to return the report in [Graphviz][] DOT format.
Use `--production` to return only `dependencies` and not `devDependencies` and
`--output` to save a file (*.json* or *.svg*) for generated report.

If you want to filter the output you can use
`--certified` to show only certified packages or
`--failed` to show only packages that failed certification.

[Graphviz]: http://www.graphviz.org/

```
$ nscm report --production --json
please wait while we process the information
[
  {
    "name": "body-parser",
    "version": "1.15.2",
    "from": "1.15.2 <1.16.0",
    "score": 100
  },
  {
    "name": "debug",
    "version": "2.2.0",
    "from": ">=2.2.0 <2.3.0",
    "score": 70
  },
  {
    "name": "ms",
    "version": "0.7.1",
    "from": "0.7.1",
    "score": 100
  },
  {
    "name": "bytes",
    "version": "2.4.0",
    "from": "2.4.0",
    "score": 100
  },
...
```

## `nscm whitelist`

Check which packages aren't certified, and start an interactive prompt to add packages to the whitelist.

```
$ nscm whitelist
please wait while we process the information

37 packages aren't certified, do you want to add them to the whitelist?
? add debug@2.2.0 Yes
? add setprototypeof@1.0.2 Yes
? add statuses@1.3.1 No
? add ee-first@1.1.1 No
? add unpipe@1.0.0 (ynaH) All

┌────────────────────────────────────┬───────────────┬────────┐
│ Package                            │ Version       │ Score  │
├────────────────────────────────────┼───────────────┼────────┤
│ debug                              │ 2.2.0         │ 70     │
├────────────────────────────────────┼───────────────┼────────┤
│ setprototypeof                     │ 1.0.2         │        │
├────────────────────────────────────┼───────────────┼────────┤
...
├────────────────────────────────────┼───────────────┼────────┤
│ source-list-map                    │ 0.1.8         │        │
├────────────────────────────────────┼───────────────┼────────┤
│ webpack-core                       │ 0.6.9         │        │
└────────────────────────────────────┴───────────────┴────────┘
35 packages added to the whitelist
```

You can also pass `--all` to add all the packages to the whitelist and `--json` to return the packages in a JSON format.

### `nscm whitelist add`

Add a package and its dependencies to the whitelist.

```
$ nscm whitelist add debug@2.x
```

If you pass only the package name, `nscm` will use `latest`.  You can also pass a semver range or a specific version. If a semver range is passed it will be resolved to the highest published version that matches the range.

### `nscm whitelist delete`

Delete a package from the whitelist.

```
$ nscm whitelist delete debug
```

### `nscm whitelist list`

Lists all whitelisted packages.

```
$ nscm whitelist list
┌────────────────────────────────────┬───────────────┬────────┐
│ Package                            │ Version       │ Score  │
├────────────────────────────────────┼───────────────┼────────┤
│ acorn                              │ 4.0.1         │        │
├────────────────────────────────────┼───────────────┼────────┤
│ isarray                            │ 2.0.1         │        │
└────────────────────────────────────┴───────────────┴────────┘
2 packages in the whitelist
```
### `nscm whitelist reset`

Removes all whitelisted packages.

## `nscm config`

### Configuration Options

* `token` - Authentication Token. If not specified, it will be fetched from `~/.npmrc` - **required**
* `registry` - Private NodeSource Certified Modules registry URL. If not specified, it will be fetched from `~/.npmrc` - **required**
* `concurrency` - Concurrency of requests to package registry - default: 15

### `nscm config set <key> <value>`

Modify the specified configuration option.

```
$ nscm config set concurrency 10
```

### `nscm config get`

Gets a configuration option

```
$ nscm config get registry
https://{registryId}.registry.nodesource.io
```

### `nscm config delete`

Deletes a configuration option.

```
$ nscm config delete token
```

### `nscm config list`

List all configuration options.

```
$ nscm config list
concurrency = 15
registry = https://{registryId}.registry.nodesource.io
```

### `nscm config reset`

Reset all configuration options to default values.

```
$ nscm config reset
```

## Authors and Contributors

<table><tbody>
<tr><th align="left">Nathan White</th><td><a href="https://github.com/nw">GitHub/nw</a></td><td><a href="http://twitter.com/_nw_">Twitter/@_nw_</a></td></tr>
<tr><th align="left">Julián Duque</th><td><a href="https://github.com/julianduque">GitHub/julianduque</a></td><td><a href="http://twitter.com/julian_duque">Twitter/@julian_duque</a></td></tr>
<tr><th align="left">Adrián Estrada</th><td><a href="https://github.com/edsadr">GitHub/edsadr</a></td><td><a href="http://twitter.com/edsadr">Twitter/@edsadr</a></td></tr>
<tr><th align="left">Max Harris</th><td><a href="https://github.com/maxharris9">GitHub/maxharris9</a></td><td><a href="http://twitter.com/maxharris9">Twitter/@maxharris9</a></td></tr>
<tr><th align="left">Tierney Cyren</th><td><a href="https://github.com/bnb">GitHub/bnb</a></td><td><a href="http://twitter.com/bitandbang">Twitter/@bitandbang</a></td></tr>
<tr><th align="left">Giovanny Gongora</th><td><a href="https://github.com/Gioyik">GitHub/Gioyik</a></td><td><a href="https://twitter.com/Gioyik">Twitter/@Gioyik</a></td></tr>
</tbody></table>

Contributions are welcomed from anyone wanting to improve this project!

## License & Copyright

**nscm** is Copyright (c) 2017 NodeSource and licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included [LICENSE.md](https://github.com/nodesource/nscm/blob/master/LICENSE.md) file for more details.