Command-Line Tools

The newrelic package installs two executables (declared in the bin field of package.json):

Command File Purpose
newrelic cli/index.mjs Command-based CLI. Its only command is validate-config.
newrelic-naming-rules bin/test-naming-rules.js Tests transaction naming rules against a list of URLs.

Run them from a project where newrelic is installed, with npx:

npx newrelic validate-config -c ./newrelic.js
npx newrelic-naming-rules ./urls.txt

newrelic validate-config

Checks that a configuration file will let the agent start. It performs the same steps the agent performs at startup:

  1. Loads the file with Node's normal module rules (import()), so the extension and the nearest package.json type decide whether it is CommonJS or an ES module.
  2. Reads the exported config (export const config = {} for ESM, exports.config = {} / module.exports.config = {} for CommonJS).
  3. Applies NEW_RELIC_* environment variable overrides, exactly as the agent does.
  4. Validates the result against the configuration JSON Schema.
  5. Checks the startup blockers — conditions that pass the schema but still stop the agent:

    Blocker key Condition Message
    agent_enabled agent_enabled is not true The agent is disabled by its configuration (agent_enabled is not true), so it will not start.
    app_name No application name An application name is required. Set app_name in your configuration file or the NEW_RELIC_APP_NAME environment variable, or the agent will not start.
    license_key No license key and serverless mode off A license key is required. Set license_key in your configuration file or the NEW_RELIC_LICENSE_KEY environment variable, or the agent will not start.
    opentelemetry opentelemetry.enabled is true but the @opentelemetry/* packages cannot be resolved from the file's location OpenTelemetry is enabled but the required @opentelemetry/* bridge packages are not installed, so the agent will not start. Install them or set opentelemetry.enabled to false.

The help text warns that server-side settings, settings overridden by high security mode, and various internal settings are not considered, because they are applied at run time or always forced by the agent.

Usage

newrelic validate-config -c <file> [options]

Options

Option Short Value Description
--config-file -c path Required. The file to validate. Allowed types are .js, .cjs, and .mjs.
--output-format -o human (default) or json Format of the validation report.
--dump -d none or full Instead of a report, print the validated configuration as a loadable file. See Dumping the configuration.
--format -f cjs (default), esm, or json Module format for --dump output. Ignored without --dump.
--help -h — Print the validate-config help and exit with 0.

Standard argument parsing rules apply (node:util.parseArgs): --config-file=./newrelic.js, -c ./newrelic.js, and -- all work. Unknown options are rejected.

Exit codes

Code Meaning
0 Valid: no schema errors and no startup blockers (or a successful dump).
1 Invalid configuration, or a command-line usage error (missing -c, unknown option, unknown command).
2 Unprocessable: the file could not be loaded, or --format is not a supported value.

Human output

For a valid file:

No configuration errors detected.

For problems, one line per error, each prefixed with the JSON path of the setting. For example, with logging.level set to a number and no license key anywhere, output similar to:

Found the following configuration errors:
  + /logging/level: must be string
  + /license_key: A license key is required. Set license_key in your configuration file or the NEW_RELIC_LICENSE_KEY environment variable, or the agent will not start.

Schema error messages come from the JSON Schema validator (ajv); blocker paths are the blocker key.

JSON output

With -o json, the report is a JSON object on stdout:

{
  "status": 1,
  "errors": [
    { "/license_key": "A license key is required. Set license_key in your configuration file or the NEW_RELIC_LICENSE_KEY environment variable, or the agent will not start." }
  ]
}

A valid file produces { "status": 0, "errors": [] }. A file that cannot be loaded produces { "status": 2, "errors": [{ "message": "Could not load configuration file \"./missing.js\": ..." }] }.

Note: Any --output-format value other than human selects JSON output; -o xml does not raise an error, it simply produces JSON.

Dumping the configuration

--dump writes the configuration to stdout as a file the agent can load, with environment variables and value normalization applied (for example a string app_name becomes an array):

npx newrelic validate-config -c ./newrelic.js --dump > ./newrelic.cjs
Form Output
--dump Only the settings present in your file, with their resolved values.
--dump full Every supported (non-internal) setting, using your values where given and defaults elsewhere.
--format esm export const config = { ... }
--format json { "config": { ... } }
--format cjs (default) exports.config = { ... }

The dump is produced only when the configuration is valid and startable. Otherwise stdout stays empty, each error is printed to stderr as <path>: <message>, and the exit code is 1. This makes --dump > file safe in scripts.

--dump takes an optional value: it consumes the next argument only if that argument does not start with - and is not a command name. Values other than full produce the plain dump.

Warning: A dump contains resolved secrets, such as a license_key taken from NEW_RELIC_LICENSE_KEY or proxy credentials. Do not commit dumped files.

Examples

# Validate a CommonJS file
npx newrelic validate-config -c ./newrelic.js

# Validate an ESM file
npx newrelic validate-config -c ./newrelic.mjs

# Machine-readable result for CI
npx newrelic validate-config -c ./newrelic.js -o json

# Check what the agent will see with production variables
NEW_RELIC_LICENSE_KEY=xxx NEW_RELIC_APP_NAME=api npx newrelic validate-config -c ./newrelic.js

# Write a complete config with every setting and its default (no comments)
npx newrelic validate-config -c ./newrelic.js --dump full --format esm > ./newrelic.mjs

Usage errors and help

  • Running newrelic with no command prints Missing command. and the general help (on stderr), and exits with 1. This includes newrelic --help without a command.
  • An unrecognized command (newrelic check) prints Unrecognized command. and the general help, exiting with 1.
  • newrelic validate-config without -c prints Must supply a configuration file to validate. and the command help, exiting with 1.
  • newrelic validate-config --help prints the command help and exits with 0.

All help text is written to stderr.

Caveats

  • The OpenTelemetry package check resolves @opentelemetry/* from the configuration file's location, which should match where your application runs.
  • Unknown nested keys (typos) are not reported, because the schema allows additional properties. See Unknown keys.
  • Environment variables present in the shell where you run the CLI affect the result. Run it with the same environment your application uses.

newrelic-naming-rules

Applies naming rules to URLs and prints how each would be normalized, so you can test rules.name patterns before deploying them.

newrelic-naming-rules (-h|--help|-?)
newrelic-naming-rules [<rules>] <urls>
Argument Description
<rules> Optional. A JSON file of additional rules as an array of [pattern, replacement] pairs, e.g. [["^/u/[0-9]+", "/u/*"]]. Loaded with require().
<urls> A file with one URL path per line (no host or protocol), such as /foo/bar.
-h, --help, -? Print help and exit with 0.

The tool loads your agent configuration the normal way (so rules.name from newrelic.js and environment variables is applied) in addition to the optional rules file. Any other number of arguments prints the help.

printf '/users/123\n/users/456/orders\n' > urls.txt
npx newrelic-naming-rules urls.txt

See Also