Editor’s note: The New Relic CLI tool was developed by IBM. It is open sourced under the Apache License 2.0.

Helping our customers go faster with confidence is a key tenet of the New Relic ethos. We provide visibility into vital data, statistics, and key performance indicators (KPIs) to help teams increase their deployment speed and cadence. But modern software teams also see automation and continuous integration and continuous delivery (CI/CD) processes as must-haves to support their Agile practices and DevOps teams. Teams want to apply the same automation concepts and tools to operate New Relic as they do other parts of their pipeline.

However, writing all the standard boilerplate code to work with New Relic’s REST API (read configuration files, connect to endpoints, send payloads, receive responses, and parse them) can be a toilsome burden and a needless distraction. Fortunately, the IBM Cloud Monitoring team, a New Relic partner, noticed that multiple internal teams were spending too much time managing boilerplate code to automate their New Relic workflows, so they created a solution to solve that problem—a New Relic CLI (command line interface) tool.

Manage New Relic tasks and resources from the CLI

New Relic CLI, open sourced and available on GitHub from IBM, is a command line tool you can use to manage New Relic resources, such as New Relic Synthetics monitors, New Relic Alerts policies and conditions, and user accounts. You can also use the CLI to backup your New Relic configuration data and restore it as needed.

Currently, you can use the New Relic CLI to manage these resources:

New Relic resourceManagement action
New Relic SyntheticsCreate, edit, and delete Synthetics monitors
Back up and restore Synthetics monitors
New Relic AlertsCreate, edit, and delete alert conditions
Create, edit, and delete alert policies
Create, edit, and delete notification channels
Back up and restore alert policies and conditions
New Relic Insights dashboardsGet dashboards
Back up and restore dashboards
Users
List users

Example use case 1: Create a Synthetics monitor

This example shows you how to use the New Relic CLI to create a Synthetics monitor:

  1. Set the New Relic admin API key (NEW_RELIC_APIKEY) for your environment. This will vary depending on your operating system, but in Linux, you’d use the export command:Export NEW_RELIC_APIKEY=xxxx-xxxxxxx-xxxxx-xxxxxx
    Tip: Refer to the New Relic docs for instructions on locating your admin API key.
  2. Create a basic definition of the monitor in JSON format (for example test.json).
    {
       "name": "Test monitorURI",
       "type": "SIMPLE"
       "frequency": 5,
       "uri": "monitorURI",
       "locations": [
         "AWS_AP_SOUTH_1",
         "AWS_EU_WEST_3",
         "AWS_US_WEST_1"
       ],
       "status": "ENABLED",
       "slaThreshold": 3,
       "options": {
    }

    Tip: See the documentation for a full list of public minion locations.

  3. Run a text substitution to replace the monitorURI with the actual URL you want to test, and generate a new file (in this example, result.json).
    .awk '{gsub(/monitorURI/,"<URL TO BE TESTED>")}1' test.json > result.json
  4. To create the new monitor, run ./nr-cli create monitor -f result.json.

From this point, you can start working with the new monitor as needed.

Example use case 2: Daily backup of a Synthetics monitor

You can also use the NewRelic CLI to create daily backups of your Synthetics monitors. Using a simple shell script and a cron job, you can quickly set up a process to back up all your monitors in a safe repository.

These four steps describe how to use the New Relic CLI to set up a daily backup job that will back up all monitors into a separate folder every day:

  1. Download the shell scripts file for backup monitors (backup_monitors.sh) from the New Relic CLI repo.
  2. Add a proper path to the script, and set it as an executable: $ chmod a+x backup_monitors.sh.
  3. Create a new cron job in your OS to schedule the shell script you just created. Use crontab -e to add new schedule job.
    0 0 */1 * * <YOUR NEW_RELIC_APIKEY="xxx-xxxx-xxx>" /<your_path>/backup-monitors.sh

    NOTE: Replace xxx-xxxx-xxx with your own NewRelic admin API key.

  4. (Optional) If you don’t want to set the NR API key in your cron job’s configuration, you can set the key inbackup_monitors.sh. Comment out the Export NEW_RELIC_APIKEY="xxx-xxxx-xxx" entry, replace the value with your API key.

The cron job should now run and back up on your monitors based on the schedule you created.

A great addition for your New Relic toolbox

The New Relic CLI also lets you easily save New Relic settings to source-control tools like Github or BitBucket; and share central configuration and settings across multiple teams and projects. For example, if your target machine can’t connect to New Relic directly, you can configure the CLI tool to use a proxy. You can also configure retries to cope with timeouts. The CLI also includes return codes, which can be very useful for CI/CD automation.

For more details on developing for the New Relic CLI, see the repo on Github.

Adilson Somensari is a senior solutions architect on the New Relic Expert Services team. An experienced APM professional, with multiple certifications in the APM industry, he has a passion for helping customers succeed with modern monitoring architectures. Adilson started his career as a Java developer, delivering distributed applications to a diverse set of industries (Auto, Banking, Telecom, Transportation) in multiple countries (United States, Canada, Portugal, Brazil), and pivoted to APM after learning that there is more to life than reading logs and stack traces. View posts by .

Interested in writing for New Relic Blog? Send us a pitch!