![Community Project header](https://github.com/newrelic/open-source-office/raw/master/examples/categories/images/Community_Project.png)
newrelic-cli
![Homebrew](https://img.shields.io/badge/dynamic/json.svg?url=https://formulae.brew.sh/api/formula/newrelic-cli.json&query=$.versions.stable&label=homebrew)
![Docker Version](https://img.shields.io/docker/v/newrelic/cli.svg?sort=semver)
The New Relic CLI is an officially supported command line interface for New Relic, released as part of the Developer Toolkit.
Overview
The New Relic CLI is a project to consolidate some of the tools that New Relic
offers for managing resources. Current scope is limited while the framework is
being developed, but the tool as-is does perform a subset of tasks.
- Entity Search: Search for entities across all your New Relic accounts
- Entity Tagging: Manage tags across all of your entities
- Deployment Markers: Easily record an APM Application deployment within
New Relic.
Getting Started
For a quick guide on getting started with the New Relic CLI, see our Getting
Started
page.
New Relic CLI Documentation
The latest New Relic CLI documentation is available in the repository's docs directory.
Installation & Upgrades
Installation options are available for various platforms. If you're running an older version of the CLI you can use these commands to update to the latest version.
MacOS
Install the New Relic CLI on MacOS via homebrew
. With homebrew
installed, run:
brew install newrelic-cli
Windows
Installation is supported on 64-bit Windows.
Scoop
scoop bucket add newrelic-cli https://github.com/newrelic/newrelic-cli.git
scoop install newrelic-cli
Chocolatey
choco install newrelic-cli
Standalone installer
A standalone MSI installer is available on the New Relic download site. You can download the installer for the latest version here.
Powershell
Silent installation of the latest version of the CLI can be achieved via the follwing Powershell command:
(New-Object System.Net.WebClient).DownloadFile("https://github.com/newrelic/newrelic-cli/releases/latest/download/NewRelicCLIInstaller.msi", "$env:TEMP\NewRelicCLIInstaller.msi"); `
msiexec.exe /qn /i "$env:TEMP\NewRelicCLIInstaller.msi" | Out-Null; `
Linux
Linux binaries can be installed via Snapcraft. With the snapd
daemon installed, run:
sudo snap install newrelic-cli
Pre-built binaries
Pre-built binaries are available for all of the above platforms. You can download the latest releases here. The binaries and their checksums are signed and can be verified against the Developer Toolkit team's public PGP key.
Verify that the fingerprint for the downloaded key matches the following:
gpg --fingerprint developer-toolkit-team@newrelic.com
86BE 01DA 9B1D A1FC F828 1409 DC9F C6B1 FCE4 7986
When verifying pre-built binaries and checksums, use the long format (the short format is not secure). For example:
gpg --keyid-format long --verify checksums.txt.sig checksums.txt
Docker
There is an official docker image that can be utilized for running commands as well.
Example Usage
Querying an APM application (using the Docker image)
# Pull the latest container
$ docker pull newrelic/cli
# Run the container interactively, remove it once the command exists
# Also must pass $NEW_RELIC_API_KEY to the container
$ docker run -it --rm \
-e NEW_RELIC_API_KEY \
newrelic/cli \
apm application get --name WebPortal --accountId 2508259
[
{
"AccountID": 2508259,
"ApplicationID": 204261368,
"Domain": "APM",
"EntityType": "APM_APPLICATION_ENTITY",
"GUID": "MjUwODI1OXxBUE18QVBQTElDQVRJT058MjA0MjYxMzY4",
"Name": "WebPortal",
"Permalink": "https://one.newrelic.com/redirect/entity/MjUwODI1OXxBUE18QVBQTElDQVRJT058MjA0MjYxMzY4",
"Reporting": true,
"Type": "APPLICATION"
}
]
See the Getting Started guide for a more in-depth introduction to the capabilities of the New Relic CLI.
Getting Help
In order to get help about what commands are available, the trusty --help
flag is here to assist. Alternatively, using just the help
subcommand also works.
newrelic --help
newrelic help
Help is also available for the nested sub-commands. For example, the with the
following command, you can retrieve help for the apm
sub-command.
newrelic apm --help
newrelic help apm
Using the CLI in this way, users are able to inspect what commands are
available, with some instruction on their usage.
Patterns
Throughout the help, you may notice common patterns. The term describe
is
used to perform list or get operations, while the create
and delete
terms
are used to construct or destroy an item, respectively.
Development
Requirements
Building
The newrelic
command will be built in bin/ARCH/newrelic
, where ARCH
is either linux
, darwin
, or windows
, depending on your build environment. You can run it directly from there or install it by moving it to a directory in your PATH
.
# Default target is 'build'
$ make
# Explicitly run build
$ make build
# Locally test the CI build scripts
# make build-ci
Testing
Before contributing, all linting and tests must pass. Tests can be run directly via:
# Tests and Linting
$ make test
# Only unit tests
$ make test-unit
# Only integration tests
$ make test-integration
Working with recipes
Core recipe library
A core library of installation recipes is included with the CLI for use within the
install
command. Recipe files are syndicated from open-install-library
and embedded in the CLI binary at release time. To fetch the latest recipe library
while developing, the following make target can be used:
make recipes
Recipe files are stored in internal/install/recipes/files
. Once files have been
fetched, they will be included in future CLI builds. If a particular version of
the recipe library is desired, the archive download URL can be passed to the make
target via the RECIPES_ARCHIVE_URL
option:
make recipes RECIPES_ARCHIVE_URL=https://github.com/newrelic/open-install-library/releases/download/v0.50.0/recipes.zip
To clean recipe files, use the recipes-clean
target:
make recipes-clean
Custom recipe files
A path can also be passed to the --localRecipes
flag when running the install
command. This will bypass the methods described above and load files from the designated
path.
Experimenting (internal New Relic usage only)
Using A/B tests, New Relic developers have the ability to gradually roll out new features.
Define an experiment
With access to Split.io, internal New Relic developers can create new A/B tests. Upon creating one, reference the exact name of the experiment in internal/split/constants.go
. Make sure this is the exact name of the experiment in Split.io.
Retrieve treatments
You can retrieve the status of the treatment by using the SplitService
.
// Retrieve a single treatment given an experiment (split)
treatment := split.SplitService.Get(split.VirtuosoCLITest)
if treatment == "on" {
// insert code here to show on treatment
} else if treatment == "off" {
// insert code here to show off treatment
} else {
// insert your control treatment code here
}
// Retrieve multiple treatments given a list of experiments (splits)
splits := []string{split.VirtuosoCLITest, split.VirtuosoCliTest2}
treatments := split.SplitService.GetAll(splits)
for split, treatment := range treatments {
fmt.Printf("Treatment for feature %s is %s\n", split, treatment)
// Evaluate treatments
}
Commit Messages
Using the following format for commit messages allows for auto-generation of
the CHANGELOG:
<type>(<scope>): <subject>
Type |
Description |
Change log? |
chore |
Maintenance type work |
No |
docs |
Documentation Updates |
Yes |
feat |
New Features |
Yes |
fix |
Bug Fixes |
Yes |
refactor |
Code Refactoring |
No |
Scope
This refers to what part of the code is the focus of the work. For example:
General:
build
- Work related to the build system (linting, makefiles, CI/CD, etc)
release
- Work related to cutting a new release
Package Specific:
newrelic
- Work related to the New Relic package
http
- Work related to the internal/http
package
alerts
- Work related to the pkg/alerts
package
Generating CLI Documentation
Note: This requires the repo to be in your GOPATH (godoc issue)
$ make docs
New Relic hosts and moderates an online forum where you can interact with New Relic employees as well as other customers to get help and share best practices.
- Roadmap - As part of the Developer Toolkit, the roadmap for this project follows the same RFC process
- Issues or Enhancement Requests - Issues and enhancement requests can be submitted in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue.
- Contributors Guide - Contributions are welcome (and if you submit a Enhancement Request, expect to be invited to contribute it yourself 😁).
- Community discussion board - Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub.
Please do not report issues with the CLI to New Relic Global Technical Support. Instead, visit the Explorers Hub
for troubleshooting and best-practices.
Issues / Enhancement Requests
Issues and enhancement requests can be submitted in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue.
Contributing
Contributions are welcome (and if you submit a Enhancement Request, expect to be invited to contribute it yourself 😁). Please review our Contributors Guide.
Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at opensource@newrelic.com.
Other Resources
There are a handful of other useful tools that this does not replace. Here are
some useful links to other tools that you might be interested in using at this
time.
- NR1 CLI:
Command line interface for managing development workflows for custom Nerdpacks on New Relic One.
- New Relic Lambda CLI: A
CLI to install the New Relic AWS Lambda integration and layers.
- New Relic Diagnostics:
A utility that automatically detects common problems with New Relic agents.
Open Source License
This project is distributed under the Apache 2 license.