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:
- Loads the file with Node's normal module rules (
import()), so the extension and the nearestpackage.jsontypedecide whether it is CommonJS or an ES module. - Reads the exported
config(export const config = {}for ESM,exports.config = {}/module.exports.config = {}for CommonJS). - Applies
NEW_RELIC_*environment variable overrides, exactly as the agent does. - Validates the result against the configuration JSON Schema.
-
Checks the startup blockers — conditions that pass the schema but still stop the agent:
Blocker key Condition Message agent_enabledagent_enabledis nottrueThe agent is disabled by its configuration (agent_enabled is not true), so it will not start.app_nameNo 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_keyNo 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.opentelemetryopentelemetry.enabledistruebut the@opentelemetry/*packages cannot be resolved from the file's locationOpenTelemetry 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-formatvalue other thanhumanselects JSON output;-o xmldoes 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_keytaken fromNEW_RELIC_LICENSE_KEYor 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
newrelicwith no command printsMissing command.and the general help (on stderr), and exits with1. This includesnewrelic --helpwithout a command. - An unrecognized command (
newrelic check) printsUnrecognized command.and the general help, exiting with1. newrelic validate-configwithout-cprintsMust supply a configuration file to validate.and the command help, exiting with1.newrelic validate-config --helpprints the command help and exits with0.
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