• Sign up

Quickly tag a set of resources

5 min

Tags help you group, search, filter, and focus the data about your entities, which can be anything from applications to hosts to services. Tagging entities using the New Relic CLI is a good candidate for automation.

In this 5-minute guide, you use the New Relic CLI to add multiple tags to one of your entities.

Before you begin

For this guide you need your New Relic personal API Key: Create it at the Account settings screen for your account.

Step 1 of 6

Install the New Relic CLI

You can download the New Relic CLI 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 6

Create your New Relic CLI profile

New Relic CLI profiles contain credentials and settings that you can apply to any CLI command.

To create your first CLI profile, run the profiles add command. Don't forget 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 API_KEY -r us
# Set the profile as default
newrelic profiles default -n tutorial

Step 3 of 6

Search for an entity

Your New Relic account might have hundreds of entities: Have a quick look by opening the Entity explorer.

In the terminal, run entity search to retrieve a list of entities from your account as JSON. In the example, you're searching for all entities with "test" in their name.

# Change the `name` to match any of your existing entities
newrelic entity search --name "test"

Step 4 of 6

If there are matching entities in your account, the query yields data in JSON format, similar to this workload example.

Select an entity from the results and look for its guid value; the guid is the unique identifier of the entity. Write it down.

{
"accountId": 123456789,
"domain": "NR1",
"entityType": "WORKLOAD_ENTITY",
"guid": "F7B7AE59FDED4204B846FB08423DB18E",
"name": "Test workload",
"reporting": true,
"type": "WORKLOAD"
},

Step 5 of 6

Add tags and tag lists to your entity

With your entity guid, you can add tags right away. You can do so by invoking the entities tags create command.

What if you want to add multiple tags? You can use tag sets for that: While tags are key-value pairs separated by colons, tag sets are comma-separated lists of tags. For example:

tag1:value1,tag2:value2

Note

Adding tags is an asynchronous operation: it could take a little while for the tags to get created.
# Adding a single tag
newrelic entity tags create --guid GUID --tag key:value
# Adding multiple tags
newrelic entity tags create --guid GUID --tag tag1:test,tag2:test

Step 6 of 6

Check that the tags are there

To make sure that the tags have been added to your entities, retrieve them using the entity tags get command. All tags associated with your entity are retrieved as a JSON array.

newrelic entity tags get --guid GUID

Tip

Tags can be deleted at any time by invoking the entity tags delete command followed by the same arguments you used to create them.

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

Next steps

Have a look at all the New Relic CLI 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.