@contrast/cli

Command-line utilities for the Contrast Node.js agent. @contrast/agent depends on this package, so the commands are available wherever the agent is installed.

Running

The package has several commands, so name the command with npx -p (plain npx @contrast/cli doesn't work):

npx -p @contrast/cli <command> [options]

Run the commands from the application's directory, with the same environment variables the application uses. They discover configuration exactly as the agent does (contrast_security.yaml and CONTRAST__* variables), so a different working directory or environment gives different results. They need a Node.js version the agent supports.

Commands

config-diagnostics

Usage: npx -p @contrast/cli config-diagnostics [options] <entrypoint>

Arguments:
  entrypoint             The entrypoint JavaScript or ESM file for the application

Options:
  -q, --quiet            suppress logging to stdout
  -o, --output <string>  output file for the generated JSON
                         (default: ./contrast_effective_config.json)
  -V, --version          output the version number
  -h, --help             display help for command

Prints the agent's effective configuration as JSON, showing each option's value and where it came from (environment variable, configuration file, Contrast UI, or default). Credentials are redacted.

Unless api.enable is false, it connects to Contrast (TeamServer) the same way the agent does at startup, so the output includes remote settings from the Contrast UI. The Status field says whether that connection succeeded and, if not, why.

The JSON goes to stdout and to the output file. --quiet only suppresses stdout. The file is still written.

system-diagnostics

Usage: npx -p @contrast/cli system-diagnostics [options]

Options:
  -q, --quiet            suppress logging to stdout
  -o, --output <string>  output file for the generated JSON
                         (default: ./contrast_system_info.json)
  -V, --version          output the version number
  -h, --help             display help for command

Prints information about the host or container the agent runs on, as JSON. This is the same system information the agent collects. It doesn't contact Contrast.

The JSON goes to stdout and to the output file. --quiet only suppresses stdout.

rewrite

Usage: npx -p @contrast/cli rewrite [options] <entrypoint>

Arguments:
  entrypoint     The entrypoint for the application

Options:
  -a, --assess   rewrite in assess mode
  -p, --protect  rewrite in protect mode
  -V, --version  output the version number
  -h, --help     display help for command

Rewrites the application's source files ahead of time and caches the results, so the agent doesn't have to rewrite them when the application starts. Starting from the entrypoint, it follows every static import, require(), and import() with a string argument, and rewrites each file it reaches.

The mode must match how the application will run:

• --protect rewrites for Protect.
• --assess rewrites for Assess. It is also the default when assess.enable is true in the configuration.
• With neither flag and Assess not enabled, it rewrites for Protect.

Results are cached in <agent.node.rewrite.cache.path>/<application name>/<agent version>/<mode>/. The cache path defaults to .contrast/ in the working directory. The agent only uses the cache when the application name, agent version, and mode all match, so rerun rewrite after upgrading the agent.

The command fails with Rewriting disabled. if agent.node.rewrite.enable or agent.node.rewrite.cache.enable is false.