pkgrep

Powerful CLI tool to find, filter & format package data in node_modules.

Installation

> npm install -g pkgrep

Usage

Find, filter & format package data in node_modules.

Usage: pkgrep [options] [name[@version] ...]

...

Options:
  -a, --all        Match all dependencies. non-zero exit if not all match.
  -d, --depth      Traversal depth. use --depth=Infinity or --depth=-1 to traverse entire dependency tree.            [default: 0]
  -f, --format     Output format string. Place variables in {curlies}.                                                [default: "{name}@{version}"]
  -t, --table      Show output in a table. Use --format to indicate desired columns. All non-variables are ignored.
  -s, --strict     Only list packages which contain all variables in --format.
  -x, --filter     Filter packages using an arbitrary ES6 expression. No return statement required. Use at own risk.
  --dev            Include development dependencies.
  --extraneous     Show extraneous dependencies                                                                       [default: true]
  --no-extraneous  Filter extraneous dependencies. This will include --dev dependencies if --dev is not enabled.
  --flatten        Flatten --json output so there is no object nesting.
  --json           Generate JSON output. Respects keys used in --format. All non-variables are ignored.
  --list-vars      List examples of possible --format & --table variables.
  --summary        Show summary after results on stderr.                                                              [default: true]
  --no-summary     Do not print any summary text to stderr. "e.g. 5 matching dependencies."
  --silent         No visual output, exit codes only.
  --unique         Only display unique lines of output.                                                               [default: true]
  --no-unique      Do not remove duplicate lines of output.
  --help           Show help
  --version        Show version number

Examples

To follow along at home, start with this:

> mkdir pkgrep-cli-test && cd pkgrep-cli-test
> npm init -f
> npm install inherits mkdirp --save

List all top-level dependencies

> pkgrep
[email protected]
[email protected]
2 matching dependencies

Traverse the node_modules hierarchy.

You can use --depth in combination with most other flags.

> pkgrep --depth=-1
[email protected]
[email protected]
[email protected]
3 matching dependencies

Check whether a package is installed

If the package is not installed you'll get a non-zero exit-code:

> pkgrep mkdirp || echo "package is not installed"
[email protected]
1 matching dependency

> pkgrep bower || echo "package is not installed"
No matching dependencies!
package is not installed

Matching Semver

You can pass any valid semver version in the format: name@semver:

> pkgrep [email protected]
No matching dependencies!

> pkgrep inherits@~2.0.0
[email protected]
1 matching dependency

Check whether multiple packages are installed

Only matched packages will be printed. Only non-zero exit code if no packages.

> pkgrep mkdirp inherits bower
[email protected]
[email protected]
2 matching dependencies.

Ensure Packages are Installed

--all will exit with failure unless all listed packages are matched.

> pkgrep --all mkdirp inherits bower || echo "Failed."
[email protected]
[email protected]
2 matching dependencies.
2 out of 3 matches.
Failed.

Include devDependencies

Use --dev to include devDependencies.

> npm install --save-dev tape
> pkgrep tape

No matching dependencies!

> pkgrep tape --dev
[email protected]
1 matching dependency

Filtering packages

pkgrep permits using arbitrary ES6 expressions. Use at own risk.

All package keys are in scope, as if the code was executed within a with statement for each package. No return statement is required for single-line expressions.

For example, we can list only dependencies that depend on tap in their devDependencies:

> pkgrep --filter="devDependencies.tap" --depth=-1
NAME     VERSION REALPATH
inherits 2.0.1   /Users/timoxley/Projects/get-dependencies/pkgrep-cli-test/node_modules/inherits
mkdirp   0.5.0   /Users/timoxley/Projects/get-dependencies/pkgrep-cli-test/node_modules/mkdirp
2 dependencies.

Custom output data format

Use --format to control output. Variables are enclosed in single {curlies}.

> pkgrep --format="{name}"
inherits
mkdirp
2 dependencies.
> pkgrep --format="{name}@{version} - {realPath}"
[email protected] - /Users/timoxley/Projects/test/pkgrep-cli-test/node_modules/inherits
[email protected] - /Users/timoxley/Projects/test/pkgrep-cli-test/node_modules/mkdirp
2 dependencies.

Print nested properties

> pkgrep --format='{name} "{scripts.test}"'
inherits "node test"
mkdirp "tap test/*.js"
2 dependencies.

List available format variables

> pkgrep --list-vars
Possible format keys:
KEY                   VALUE
name                  pkgrep-cli-test
version               1.0.0
description
main                  index.js
scripts.test          echo "Error: no test specified" && exit 1
keywords
author.name           Tim Oxley
author.email          [email protected]
license               ISC
dependencies.inherits ^2.0.1
dependencies.mkdirp   ^0.5.0
devDependencies.tape  ^3.4.0
readme                ERROR: No README data found!
_id                   [email protected]
realName              pkgrep-cli-test
extraneous            false
path                  /Users/timoxley/test/pkgrep-cli-test
realPath              /Users/timoxley/test/pkgrep-cli-test
link
depth                 0
peerDependencies      [object Object]
root                  true

Table output

Formatting courtesy of columnify.

> pkgrep --table

pkgrep --table --depth=-1
NAME           VERSION
inherits       2.0.1
mkdirp         0.5.0
minimist       0.0.8
deep-equal     0.2.1
defined        0.0.0
glob           3.2.11
minimatch      0.3.0
lru-cache      2.5.0
sigmund        1.0.0
object-inspect 0.4.0
resumer        0.0.0
through        2.3.6
12 dependencies.

Control table columns

To make it easy to flip between text and table output, all whitespace & non-variable characters in the --format string are totally ignored. The variables are collected and used as table columns.

> pkgrep --format="{name}@{version} - {realPath}" --table
NAME     VERSION REALPATH
inherits 2.0.1   /Users/timoxley/Projects/get-dependencies/pkgrep-cli-test/node_modules/inherits
mkdirp   0.5.0   /Users/timoxley/Projects/get-dependencies/pkgrep-cli-test/node_modules/mkdirp
2 dependencies.

JSON output

Use --json to get JSON Output.

> pkgrep --format="{name} {scripts.test}" --json
[
  {
    "name": "inherits",
    "scripts": {
      "test": "node test"
    }
  },
  {
    "name": "mkdirp",
    "scripts": {
      "test": "tap test/*.js"
    }
  }
]
2 dependencies.

Flatten JSON output

Use --flatten with --json to remove JSON object nesting.

> pkgrep --format="{name} {scripts.test}" --json --flatten
[
  {
    "name": "inherits",
    "scripts.test": "node test"
  },
  {
    "name": "mkdirp",
    "scripts.test": "tap test/*.js"
  }
]
2 dependencies.

TODO

• Gather more usecases.
• Integration tests.

See Also

• timoxley/pkgfiles
• timoxley/pkgrep
• timoxley/pkgcount
• timoxley/installed

License

MIT