• Sign up

Get started with the New Relic CLI

20 min

Access the New Relic platform from the comfort of your terminal: you can use the New Relic CLI to manage entity tags, define workloads, record deployment markers, and much more. Our CLI has been designed for automating common tasks in your DevOps workflow. This guide walks you through the essentials of New Relic CLI, from install and configuration to basic usage.

Before you begin

For this guide you just need:

  1. Your New Relic personal API Key, which you can create from the Account settings of your New Relic account
  2. An instrumented application in your New Relic account

Step 1 of 10

Install the New Relic CLI

The New Relic CLI can be downloaded via Homebrew (macOS), Scoop (Windows), and Snapcraft (Linux). You can also download pre-built binaries for all platforms, including .deb and .rpm packages, and our Windows x64 .msi installer.

Linux

With Snapcraft installed, run:

sudo snap install newrelic-cli

macOS

With Homebrew installed, run:

brew install newrelic-cli

Windows

With Scoop installed, run:

scoop bucket add newrelic-cli https://github.com/newrelic/newrelic-cli.git
scoop install newrelic-cli

Step 2 of 10

Create your New Relic CLI profile

Now that you've installed the New Relic CLI, it's time to create your first profile. Profiles contain credentials and settings that you can apply to any CLI command, which is useful when switching between accounts.

To create your first CLI profile, run the profiles add command. Note that you need to set the region of your New Relic account: use -r to set either us or eu (this is required).

# Create the tutorial account for the US region
newrelic profiles add -n tutorial --apiKey YOUR_NEW_RELIC_API_KEY -r YOUR_REGION
# Set the profile as defaults
newrelic profiles default -n tutorial

Step 3 of 10

Get your application details

In this example, you are going to add tags to the application you've instrumented with New Relic. Tags are key-value pairs that can help you organize and filter your entities. An entity (for example, an application) can have a maximum of 100 key-value pairs tied to it.

Before searching for your application using the New Relic CLI, write down or copy your Account ID and the name of your application in New Relic - you need both to find applications in the New Relic platform.

Step 4 of 10

The New Relic CLI can retrieve your application details as a JSON object.

To search for your APM application use the apm application search command. If you get an error, check that the account ID and application name you provided are correct.

newrelic apm application search --accountId YOUR_ACCOUNT_ID --name NAME_OF_YOUR_APP

Step 5 of 10

If the account ID is valid, and the application name exists in your account, apm application search yields data similar to this example.

When you've successfully searched for your application, look for the guid value. It's a unique identifier for your application. You should copy it or write it down.

[
{
accountId: YOUR_ACCOUNT_ID,
applicationId: YOUR_APP_ID,
domain: 'APM',
entityType: 'APM_APPLICATION_ENTITY',
guid: 'A_LONG_GUID',
name: 'NAME_OF_YOUR_APP',
permalink: 'https://one.newrelic.com/redirect/entity/A_LONG_GUID',
reporting: true,
type: 'APPLICATION',
},
];

Step 6 of 10

Add a simple tag to your application

Now that you have the GUID, you can point the New Relic CLI directly at your application. Adding a tag is the simplest way to try out the CLI capabilities (don't worry, tags can be deleted by using entity tags delete).

Let's suppose that you want to add an environment tag to your application. Go ahead and add the dev:testing tag⁠ (or any other key-value pair) to your application using the entities tags create command.

newrelic entity tags create --guid YOUR_APP_GUID --tag devkit:testing

Step 7 of 10

What if you want to add multiple tags? Tag sets come to the rescue! While tags are key-value pairs separated by colons, tag sets are comma separated lists of tags. For example:

tag1:value1,tag2:value2

To add multiple tags at once to your application, modify and run the following snippet.

newrelic entity tags create --guid YOUR_APP_GUID --tag tag1:test,tag2:test

Adding tags is an asynchronous operation: this means it could take a while for the tags to get created.

Step 8 of 10

You've created and added some tags to your application, but how do you know they're there? You need to retrieve your application's tags.

To retrieve your application's tags, use the entity tags get command.

newrelic entity tags get --guid YOUR_APP_GUID

All tags associated with your application are retrieved as a JSON array.

[
{
Key: 'tag1',
Values: ['true'],
},
{
Key: 'tag2',
Values: ['test'],
},
{
Key: 'tag3',
Values: ['testing'],
},
// ...
];

Step 9 of 10

Bonus step: Create a deployment marker

Deployments of applications often go wrong. Deployment markers are labels that, when attached to your application data, help you track deployments and troubleshoot what happened.

To create a deployment marker, run the apm deployment create command using the same Application ID from your earlier search.

newrelic apm deployment create --applicationId YOUR_APP_ID --revision $(git describe --tags --always)

Step 10 of 10

Notice that the JSON response includes the revision and timestamp of the deployment. This workflow could be built into a continuous integration or continuous deployment (CI/CD) system to help indicate changes in your application's behavior after deployments.

Here is an example.

{
"id": 37075986,
"links": {
"application": 204261368
},
"revision": "v1.2.4",
"timestamp": "2020-03-04T15:11:44-08:00",
"user": "Developer Toolkit Test Account"
}

Next steps

Have a look at all the available commands. For example, you could create a New Relic workflow using workload create

If you'd like to engage with other community members, visit our New Relic Explorers Hub page. We welcome feature requests or bug reports on GitHub.