report-toolkit Command-Line Usage

You must supply a command to rtk. A single command must immediately follow the rtk executable.

The command must be one of the following:

Any “boolean” flag—an option without an argument—can be explicitly disabled by prepending --no- to the option name. For example, to explicitly disable color output when comparing report-A.json to report-B.json:

This is applicable to both global and command-specific boolean flags.

Configuration will be read from a JavaScript file named .rtkrc.js or rtk.config.js. If one is not found in the current working directory, the search for one of these files will continue until one is found, the current user’s “home” directory is found, or the root of the filesystem is found (see cosmiconfig for further details on the file-finding algorithm).

Other formats, including JSON, YAML, TOML, etc., are explicitly not supported. Configuration cannot be stored in a package.json, either. Sorry!

TODO: Write configuration docs and link to them; see #66

These options can be used in tandem with any command.

In the case of --help and --version, no command is required.

Supply an explicit path to a report-toolkit config file. This option is only necessary if your config file has non-standard location and/or name.

The same restrictions as described above in About Configuration apply.

Color output is enabled by default when a TTY is available. If there is no TTY (like in a subprocess, or when piped), specify --color to force color.

Enables debug output. --verbose is an alias of --debug; their behavior is identical.

This can be noisy.

Using --debug is equivalent to setting the environment variable DEBUG=rtk*. Further granularity can be achieved by appending package or module name(s) separated by colons, e.g., DEBUG=rtk:cli* will show all debug output from the CLI package. Package names follow a pattern of rtk:<package name>[:..submodule name or path].

Debug output is sent to STDERR.

Displays help text, then exits. --help can be used by itself (to see global options and the list of commands), or combined with any command to see command-specific options.

Outputs the version of rtk to STDOUT then exits.

The diff command compares two (2) Diagnostic Report files and outputs the difference. Unlike a typical diff tool, the output is purpose-built for comparing reports.

To use diff with the defaults:

diff requires two (2) paths to Diagnostic Report files.

The output of diff contains four (4) fields:

In the default, tabular output, each “Op” and “Field” pair will be color-coded based on its operation. “Modified” is yellow, “deleted” is red, and “added” is green.

Unlike other commands, the output of diff depends on the order of the two files given; the results will be the same, but reversed.

This section describes the default behavior of rtk diff.

This group of options allows the user to fine-tune which fields (properties) rtk diff considers when comparing report files.

Explicitly include one or more fields in the comparison. If this option is used, rtk will only consider the field(s) specified (and any nested fields or array items).

This option can be used multiple times.

To only compare field header (and its nested fields) when comparing report-A.json and report-B.json:

To only compare fields header.commandLine (and its items) and header.cwd when comparing report-A.json and report-B.json:

Explicitly exclude one or more fields in the comparison. If this option is used, rtk will consider the defaults, then further exclude the specified fields.

This option can be used multiple times.

To exclude field header (and its nested fields) when comparing report-A.json and report-B.json (but otherwise use the defaults):

To exclude fields header.commandLine (and its items) and header.cwd when comparing report-A.json and report-B.json (but otherwise use the defaults):

By default, rtk excludes certain properties to reduce noise. Use --all if you would like to include the entire Diagnostic Report when comparing.

--all cannot be used with --includeProp/-i or --excludeProp/-x.

To compare the entirety of report-A.json and report-B.json:

diff supports the following common output options:

The inspect command runs heuristics, called Rules, on one or more Diagnostic Reports. If a Rule finds a potential problem, it will output a message. Some messages may be warnings, and others may be purely informational.

The purpose of inspect is to automate the discovery of potential problems in a Node.js process. These may range from runaway resource consumption, to nonstandard configuration, to hung event loops. If a developer can closely inspect a Diagnostic Report to uncover a problem, a Rule can automate this process. Also: developers like to automate things.

inspect draws heavily from ESLint. Like ESLint, report-toolkit ships with built-in Rules and a recommended configuration. Also like ESLint, developers can create and distribute their own Rules.

To use inspect with the default “recommended” configuration:

To use inspect with the default “recommended” configuration across three (3) report files:

inspect’s output contains four (4) fields:

In the default, tabular output, the severities ERROR, WARNING and INFO will be respectively highlighted in red, yellow, and blue.

inspect allows filtering of Messages by their severity.

The minimum threshold for Message severity, as defined by severity. In other words, any Message with a severity “lower” than this will be suppressed.

Allowed values for severity, in descending order of severity:

The severity argument is case-insensitive. The default severity is WARNING.

inspect supports the following common output options:

Node.js Diagnostic Reports contain the entirety of a process’ execution environment in the environmentVariables field.

environmentVariables can contain things like API keys, tokens, and other secrets. It’s important to keep these secrets from leaking, and a Node.js Diagnostic Report is one potential source of leaks.

When provided one or more report files, redact command redacts known secrets and secret-ish values from this field—while retaining the key name. Values are replaced with the string [REDACTED].

The redact command is essentially a shortcut for transform -t redact.

This command will echo a redacted version of report.json to STDOUT:

The output is the input—Node.js Diagnostic Reports—but with secrets redacted from the environmentVariables field.

The default behavior of redact is to output the same format which Node.js Diagnostic Report files use: pretty-printed JSON.

Redacts file(s) in-place. In other words, this reads the file(s), redacts secrets, and overwrites them.

When --replace is used, redact will not echo anything to STDOUT.

redact does not support transformers, and is limited to JSON output! If you need to use a transformer, use the transform command instead (which redacts by default).

Since redact defaults to pretty-printed output, it supports --no-pretty.

transform converts a Node.js Diagnostic Report into a different format.

While --transform can be used with the output of other commands, the transform command works directly on report files.

As with any other command, reports will be redacted by default.

To transform Node.js Diagnostic Report file report.json into non-pretty-printed (ugly?) JSON:

The behavior of the below example is identical to rtk redact report.json:

Generally, you will use the --transform <transformer> option to change the transformer. Notably, the transform command works with any transformer.

To transform Node.js Diagnostic Report file report.json into CSV (for reasons):

The output of transform is based entirely on which transform(s) are used.

The default behavior of transform is to output the original Node.js Diagnostic Report file(s), redacted, and in compressed (non-pretty-printed) JSON format.

transform supports the following common output options:

Most of these options are available across most commands. Exceptions include:

Redirect output to a file.

The above is equivalent to the following in a POSIX shell:

This will disable automatic redaction of secrets from the environmentVariables field.

Transforms command output into various formats.

This option can be repeated, creating a transformer chain. This works when the output of a transformer is valid input for a subsequent transformer. Note that each transformer can only be used once.

Allowed values of transformer:

For further customization of transformer output, see Transformer-Specific Options.

Transformers, when used either via the transform command, or the --transform / -t option, have their own options. These options only apply when the transformer in question is used.

The json transformer has only one (1) option, --pretty.

Pretty-prints the JSON output. When used with diff, this defaults to false.

These options allow tweaking of the tabular display.

Sets the maximum width, columns, of the table output. By default, the table will stretch the length of the terminal. In a non-TTY situation, the default width will be 80 characters.

If --no-truncate is used, this option will be ignored.

Truncate the values displayed in the table to fit the columns. This is enabled by default, as certain fields (e.g., environmentVariables.PATH) are likely to be very long.