A command-line interface for interacting with New Relic APIs.
- APM Applications: List applications, view details, and retrieve available metrics
- Alert Policies: List and inspect alert policy configurations
- Dashboards: List and view dashboard details
- Deployments: Track deployment markers for applications
- Entities: Search across all New Relic entity types
- Log Parsing Rules: Create, list, and delete log parsing rules
- NerdGraph: Execute arbitrary GraphQL queries
- NRQL: Run NRQL queries directly from the command line
- Synthetic Monitors: List and inspect synthetic monitoring configurations
- Users: List and view user details
- Multiple Output Formats: Table, JSON, and plain (scriptable) output
- Secure Credential Storage: macOS Keychain or encrypted config file
Homebrew (recommended)
brew install open-cli-collective/tap/newrelic-cliNote: This installs from our third-party tap.
Chocolatey
choco install nrq-cliWinget
winget install OpenCLICollective.newrelic-cliSnap
sudo snap install ocli-newrelicNote: After installation, the command is available as
nrq.
APT (Debian/Ubuntu)
# Add the GPG key
curl -fsSL https://open-cli-collective.github.io/linux-packages/keys/gpg.asc | sudo gpg --dearmor -o /usr/share/keyrings/open-cli-collective.gpg
# Add the repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/open-cli-collective.gpg] https://open-cli-collective.github.io/linux-packages/apt stable main" | sudo tee /etc/apt/sources.list.d/open-cli-collective.list
# Install
sudo apt update
sudo apt install nrqNote: This is our third-party APT repository, not official Debian/Ubuntu repos.
DNF/YUM (Fedora/RHEL/CentOS)
# Add the repository
sudo tee /etc/yum.repos.d/open-cli-collective.repo << 'EOF'
[open-cli-collective]
name=Open CLI Collective
baseurl=https://open-cli-collective.github.io/linux-packages/rpm
enabled=1
gpgcheck=1
gpgkey=https://open-cli-collective.github.io/linux-packages/keys/gpg.asc
EOF
# Install
sudo dnf install nrqNote: This is our third-party RPM repository, not official Fedora/RHEL repos.
Binary download
Download .deb, .rpm, or .tar.gz from the Releases page - available for x64 and ARM64.
# Direct .deb install
curl -LO https://github.com/open-cli-collective/newrelic-cli/releases/latest/download/nrq_VERSION_linux_amd64.deb
sudo dpkg -i nrq_VERSION_linux_amd64.deb
# Direct .rpm install
curl -LO https://github.com/open-cli-collective/newrelic-cli/releases/latest/download/nrq-VERSION.x86_64.rpm
sudo rpm -i nrq-VERSION.x86_64.rpmgo install github.com/open-cli-collective/newrelic-cli/cmd/nrq@latest# 1. Configure your API key (stored securely)
nrq config set-api-key
# 2. Set your account ID
nrq config set-account-id 12345678
# 3. Verify configuration
nrq config show
# 4. Start using the CLI
nrq apps list| Variable | Description | Required |
|---|---|---|
NEWRELIC_API_KEY |
Your New Relic User API key (starts with NRAK-) |
Yes |
NEWRELIC_ACCOUNT_ID |
Your New Relic account ID | Yes (for most commands) |
NEWRELIC_REGION |
API region: US (default) or EU |
No |
# Set API key (interactive prompt)
nrq config set-api-key
# Set API key (inline)
nrq config set-api-key NRAK-xxxxxxxxxxxxxxxxxxxx
# Set account ID
nrq config set-account-id 12345678
# Set region (US or EU)
nrq config set-region EU
# View current configuration
nrq config show
# Delete stored credentials
nrq config delete-api-key
nrq config delete-account-id| Platform | Storage Method | Location |
|---|---|---|
| macOS | System Keychain | Secure keychain storage |
| Linux | Config file | ~/.config/newrelic-cli/credentials (0600 permissions) |
- Environment variables (highest priority)
- Stored credentials (CLI config)
- Default values (lowest priority)
Generate shell completions for tab completion support:
# Bash (Linux)
nrq completion bash > /etc/bash_completion.d/newrelic-cli
# Bash (macOS with Homebrew)
nrq completion bash > $(brew --prefix)/etc/bash_completion.d/newrelic-cli
# Zsh
nrq completion zsh > "${fpath[1]}/_newrelic-cli"
# Fish
nrq completion fish > ~/.config/fish/completions/newrelic-cli.fish
# PowerShell
nrq completion powershell >> $PROFILERun nrq completion --help for detailed setup instructions.
| Flag | Short | Default | Description |
|---|---|---|---|
--output |
-o |
table |
Output format: table, json, or plain |
--no-color |
false |
Disable colored output | |
--help |
-h |
Show help for any command | |
--version |
Show version information |
Most commands have shorter aliases for convenience:
| Command | Aliases |
|---|---|
applications |
apps, app |
alerts |
alert |
dashboards |
dashboard, dash |
deployments |
deployment, deploy |
entities |
entity, ent |
logs |
log |
synthetics |
synthetic, syn |
nerdgraph |
ng, graphql |
users |
user |
Manage APM applications.
List all APM applications in your account.
nrq apps list
nrq apps list -o json
nrq apps list -o plainTable Output:
ID NAME LANGUAGE STATUS
12345678 production-api ruby green
23456789 staging-api ruby gray
34567890 frontend-service nodejs green
Get details for a specific application.
nrq apps get <app-id>
nrq apps get 12345678
nrq apps get 12345678 -o jsonTable Output:
ID: 12345678
Name: production-api
Language: ruby
Health Status: green
Reporting: true
Last Reported: 2024-01-15T10:30:00Z
List available metrics for an application.
nrq apps metrics <app-id>
nrq apps metrics 12345678Manage alert policies.
List all alert policies.
nrq alerts policies list
nrq alerts policies list -o jsonTable Output:
ID NAME INCIDENT PREFERENCE
12345 Production Alerts PER_POLICY
23456 Staging Alerts PER_CONDITION
Get details for a specific alert policy.
nrq alerts policies get <policy-id>
nrq alerts policies get 12345Manage dashboards.
List all dashboards.
nrq dashboards list
nrq dashboards list -o jsonTable Output:
GUID NAME PAGES
ABC123... Production Overview 3
DEF456... API Performance 2
Get details for a specific dashboard.
nrq dashboards get <guid>
nrq dashboards get "ABC123..."Manage deployment markers.
Aliases: deployment, deploy
List deployments for an application with optional time filtering.
# By app ID
nrq deployments list 12345678
# By application name
nrq deployments list --name "My Application"
# By entity GUID
nrq deployments list --guid "MjcxMjY0MHxBUE18..."
# With time filtering
nrq deployments list 12345678 --since "7 days ago" --until "yesterday"
# Limit results
nrq deployments list 12345678 --limit 10| Flag | Short | Description |
|---|---|---|
--name |
-n |
Application name to look up |
--guid |
-g |
Entity GUID to look up |
--since |
Show deployments after this time | |
--until |
Show deployments before this time | |
--limit |
-l |
Limit number of results |
Time formats: Supports relative times (7 days ago, 2 hours ago), keywords (now, yesterday), and standard formats (2025-01-14, RFC3339).
Table Output:
ID REVISION DESCRIPTION USER TIMESTAMP
9876 v1.2.3 Bug fixes alice 2024-01-15T10:30:00Z
9875 v1.2.2 Feature release bob 2024-01-14T15:00:00Z
Create a deployment marker for an application.
# By app ID
nrq deployments create 12345678 --revision v1.2.3
# By application name
nrq deployments create --name "My Application" --revision v1.2.3
# By entity GUID
nrq deployments create --guid "MjcxMjY0MHxBUE18..." --revision v1.2.3
# Full example
nrq deployments create 12345678 \
--revision v1.2.3 \
--description "Bug fixes and performance improvements" \
--user "alice" \
--changelog "Fixed memory leak, improved cache hit rate"| Flag | Short | Required | Description |
|---|---|---|---|
--name |
-n |
No* | Application name to look up |
--guid |
-g |
No* | Entity GUID to look up |
--revision |
-r |
Yes | Deployment revision/version |
--description |
-d |
No | Deployment description |
--user |
-u |
No | User who deployed |
--changelog |
-c |
No | Changelog information |
*One of app ID (positional), --name, or --guid is required.
Search deployments across all applications using NRQL WHERE clause syntax.
# Search by user
nrq deployments search "user = 'jane.doe@example.com'"
# Search by revision pattern
nrq deployments search "revision LIKE 'v2%'"
# Search with time range
nrq deployments search "description LIKE '%hotfix%'" --since "30 days ago"
# Limit results
nrq deployments search "changelog IS NOT NULL" --limit 50| Flag | Short | Description |
|---|---|---|
--since |
Search from this time | |
--until |
Search until this time | |
--limit |
-l |
Maximum results (default: 100) |
Table Output:
TIMESTAMP APP NAME REVISION DESCRIPTION USER
2024-01-15T10:30:00Z production-api v2.1.0 Hotfix jane.doe
2024-01-14T15:00:00Z staging-api v2.0.9 Bug fixes bob
Search and manage New Relic entities.
Aliases: entity, ent
Search for entities using NRQL-style queries.
nrq entities search <query>Examples:
# Find all applications
nrq entities search "type = 'APPLICATION'"
# Find by name pattern
nrq entities search "name LIKE 'production%'"
# Find by domain
nrq entities search "domain = 'APM'"
# Combined conditions
nrq entities search "type = 'APPLICATION' AND name LIKE 'prod%'"Table Output:
GUID NAME TYPE DOMAIN ACCOUNT ID
ABC123... production-api APPLICATION APM 12345678
DEF456... production-web APPLICATION APM 12345678
Manage log parsing rules.
List all log parsing rules.
nrq logs rules list
nrq logs rules list -o jsonTable Output:
ID DESCRIPTION ENABLED UPDATED
abc-123... Parse user login events true 2024-01-15T10:00:00Z
def-456... Extract error codes false 2024-01-10T08:00:00Z
Create a log parsing rule.
nrq logs rules create [flags]| Flag | Short | Required | Description |
|---|---|---|---|
--description |
-d |
Yes | Rule description |
--grok |
-g |
Yes | GROK pattern for parsing |
--nrql |
-n |
Yes | NRQL matching condition |
--enabled |
-e |
No | Enable the rule (default: true) |
--lucene |
-l |
No | Lucene filter expression |
Example:
nrq logs rules create \
--description "Parse user login events" \
--grok "User %{UUID:user_id} logged in from %{IP:ip_address}" \
--nrql "SELECT * FROM Log WHERE message LIKE 'User % logged in%'" \
--enabled trueUpdate an existing log parsing rule. Only specified fields are modified.
nrq logs rules update <rule-id> [flags]| Flag | Short | Description |
|---|---|---|
--description |
-d |
Rule description |
--grok |
-g |
GROK pattern |
--nrql |
-n |
NRQL matching condition |
--lucene |
-l |
Lucene filter expression |
--enabled |
-e |
Enable the rule |
--disabled |
Disable the rule |
Examples:
# Update description only
nrq logs rules update abc-123 --description "Updated description"
# Disable a rule
nrq logs rules update abc-123 --disabled
# Update multiple fields
nrq logs rules update abc-123 \
--grok "%{IP:client} %{WORD:method}" \
--enabledDelete a log parsing rule. Requires confirmation unless --force is specified.
# With confirmation prompt
nrq logs rules delete abc-123-def-456
# Skip confirmation
nrq logs rules delete abc-123-def-456 --force| Flag | Short | Description |
|---|---|---|
--force |
-f |
Skip confirmation prompt |
Execute NerdGraph GraphQL queries.
Aliases: ng, graphql
Execute a GraphQL query against the NerdGraph API.
nrq nerdgraph query <graphql-query>Examples:
# Get current user info
nrq nerdgraph query '{ actor { user { email name } } }'
# List accounts
nrq nerdgraph query '{ actor { accounts { id name } } }'
# Complex query
nrq nerdgraph query '{
actor {
account(id: 12345678) {
name
nrql(query: "SELECT count(*) FROM Transaction") {
results
}
}
}
}'Execute NRQL queries.
Execute an NRQL query against your account.
nrq nrql query <nrql-query>Examples:
# Transaction count
nrq nrql query "SELECT count(*) FROM Transaction SINCE 1 hour ago"
# Average response time by app
nrq nrql query "SELECT average(duration) FROM Transaction FACET appName SINCE 1 day ago"
# Error rate
nrq nrql query "SELECT percentage(count(*), WHERE error IS true) FROM Transaction SINCE 1 hour ago"
# Top slow transactions
nrq nrql query "SELECT average(duration), count(*) FROM Transaction FACET name SINCE 1 hour ago LIMIT 10"Manage synthetic monitors.
List all synthetic monitors.
nrq synthetics list
nrq synthetics list -o jsonTable Output:
ID NAME TYPE STATUS FREQUENCY
abc-123... Production Health SIMPLE ENABLED 5
def-456... API Endpoint Check API ENABLED 1
Get details for a specific synthetic monitor.
nrq synthetics get <monitor-id>
nrq synthetics get abc-123-def-456Manage users.
List all users in your account.
nrq users list
nrq users list -o jsonTable Output:
ID NAME EMAIL ROLE
12345 Alice Smith alice@example.com admin
23456 Bob Jones bob@example.com user
Get details for a specific user.
nrq users get <user-id>
nrq users get 12345Configure nrq credentials.
Set the New Relic API key.
# Interactive (recommended)
nrq config set-api-key
# Inline (less secure - visible in shell history)
nrq config set-api-key NRAK-xxxxxxxxxxxxxxxxxxxxSet the New Relic account ID.
nrq config set-account-id 12345678Set the New Relic region.
nrq config set-region US # Default
nrq config set-region EU # European datacenterShow current configuration status.
nrq config showOutput:
Configuration Status:
API Key: NRAK-xx...xxxx (stored)
Account ID: 12345678 (environment)
Region: US (default)
Storage: macOS Keychain (secure)
Delete the stored API key. Requires confirmation unless --force is specified.
# With confirmation prompt
nrq config delete-api-key
# Skip confirmation
nrq config delete-api-key --force| Flag | Short | Description |
|---|---|---|
--force |
-f |
Skip confirmation prompt |
Delete the stored account ID. Requires confirmation unless --force is specified.
# With confirmation prompt
nrq config delete-account-id
# Skip confirmation
nrq config delete-account-id --force| Flag | Short | Description |
|---|---|---|
--force |
-f |
Skip confirmation prompt |
Human-readable tabular format with headers and aligned columns.
nrq apps list
nrq apps list -o tableMachine-readable JSON output for programmatic use.
nrq apps list -o jsonTab-separated values without headers, ideal for shell scripting.
nrq apps list -o plain# Get all app IDs
nrq apps list -o plain | cut -f1
# Get app ID by name
nrq apps list -o json | jq -r '.[] | select(.name == "production-api") | .id'# Deploy with git info
nrq deployments create $APP_ID \
--revision "$(git rev-parse --short HEAD)" \
--description "$(git log -1 --pretty=%B)" \
--user "$(git config user.name)"# Check for unhealthy apps
nrq apps list -o json | jq -r '.[] | select(.health_status != "green") | .name'# Record deployment for all production apps
nrq apps list -o json | \
jq -r '.[] | select(.name | startswith("prod")) | .id' | \
xargs -I {} nrq deployments create {} --revision v1.0.0# Get error count as a number
ERROR_COUNT=$(nrq nrql query "SELECT count(*) FROM TransactionError SINCE 1 hour ago" | jq '.results[0].count')
echo "Errors in last hour: $ERROR_COUNT"| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error (API error, invalid arguments, etc.) |
The api package can be imported and used as a Go library:
package main
import (
"fmt"
"log"
"github.com/open-cli-collective/newrelic-cli/api"
)
func main() {
// Create client from environment variables
client, err := api.New()
if err != nil {
log.Fatal(err)
}
// Or with explicit configuration
client = api.NewWithConfig(api.ClientConfig{
APIKey: "NRAK-xxxxxxxxxxxxxxxxxxxx",
AccountID: "12345678",
Region: "US",
})
// List applications
apps, err := client.ListApplications()
if err != nil {
log.Fatal(err)
}
for _, app := range apps {
fmt.Printf("%d: %s (%s)\n", app.ID, app.Name, app.HealthStatus)
}
// Execute NRQL query
result, err := client.QueryNRQL("SELECT count(*) FROM Transaction SINCE 1 hour ago")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Results: %+v\n", result)
// Execute GraphQL query
response, err := client.NerdGraphQuery(`{ actor { user { email } } }`, nil)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Response: %+v\n", response)
}| Method | Description |
|---|---|
ListApplications() |
List all APM applications |
GetApplication(id) |
Get application details |
ListApplicationMetrics(id) |
List available metrics |
ListAlertPolicies() |
List alert policies |
GetAlertPolicy(id) |
Get policy details |
ListDashboards() |
List dashboards |
GetDashboard(guid) |
Get dashboard details |
ListDeployments(appID) |
List deployments |
CreateDeployment(...) |
Create deployment marker |
SearchEntities(query) |
Search entities |
ListLogParsingRules() |
List log parsing rules |
CreateLogParsingRule(...) |
Create parsing rule |
DeleteLogParsingRule(id) |
Delete parsing rule |
GetLogParsingRule(id) |
Get parsing rule by ID |
UpdateLogParsingRule(id, update) |
Update parsing rule |
QueryNRQL(query) |
Execute NRQL query |
NerdGraphQuery(query, vars) |
Execute GraphQL query |
ListSyntheticMonitors() |
List synthetic monitors |
GetSyntheticMonitor(id) |
Get monitor details |
ListUsers() |
List users |
GetUser(id) |
Get user details |
Important: New Relic Entity GUIDs are NOT standard UUIDs. They are base64-encoded, pipe-delimited strings with a specific structure:
base64(version|domain|type|id)
| Encoded GUID | Decoded |
|---|---|
MXxBUE18QVBQTElDQVRJT058MTIzNDU2Nzg= |
1|APM|APPLICATION|12345678 |
MXxWSVp8REFTSEJPQVJEfDEyMzQ1 |
1|VIZ|DASHBOARD|12345 |
The EntityGUID type provides methods for working with these identifiers:
guid := api.EntityGUID("MXxBUE18QVBQTElDQVRJT058MTIzNDU2Nzg=")
// Parse components
version, domain, entityType, entityID, err := guid.Parse()
// Get specific components
domain, err := guid.Domain() // "APM"
entityType, err := guid.EntityType() // "APPLICATION"
entityID, err := guid.EntityID() // "12345678"
// For APM applications, extract the app ID
appID, err := guid.AppID() // "12345678"
// Validate format
if err := guid.Validate(); err != nil {
log.Printf("Invalid GUID: %v", err)
}
// Check if a string looks like a GUID
if api.IsValidEntityGUID(identifier) {
// Likely a GUID, not a name or numeric ID
}Methods using Entity GUIDs:
GetDashboard(guid)- Takes an EntityGUIDSearchEntities(query)- Returns entities with GUIDs
Methods using numeric IDs:
GetApplication(id)- Takes an integer IDGetAlertPolicy(id)- Takes an integer IDGetUser(id)- Takes a string ID
The APIKey type provides type-safe handling of New Relic User API keys:
// Create and validate an API key
key, warning, err := api.NewAPIKey("NRAK-ABCDEFGHIJ1234567890")
if err != nil {
log.Fatal(err)
}
if warning != "" {
log.Printf("Warning: %s", warning) // Non-NRAK prefix warning
}
// Validate an existing key
warning, err = key.Validate()
// Check prefix
if key.HasNRAKPrefix() {
// Standard User API key
}Valid User API keys start with NRAK- and are typically 40+ characters. Keys without the NRAK- prefix will validate successfully but return a warning.
The AccountID type provides type-safe handling of New Relic account identifiers:
// Create and validate an account ID
accountID, err := api.NewAccountID("12345678")
if err != nil {
log.Fatal(err) // Empty, non-numeric, or non-positive
}
// Get as integer (no error check needed - already validated)
id := accountID.Int()
// Check if empty
if accountID.IsEmpty() {
log.Fatal("Account ID required")
}
// Validate an existing AccountID
if err := accountID.Validate(); err != nil {
log.Fatal(err)
}Account IDs must be positive integers. The Int() method provides pre-validated integer conversion without requiring error handling.
The API package provides structured error types and helper functions:
Error Types:
// APIError - HTTP API errors
var apiErr *api.APIError
if errors.As(err, &apiErr) {
fmt.Printf("HTTP %d: %s\n", apiErr.StatusCode, apiErr.Message)
}
// GraphQLError - NerdGraph query errors
var gqlErr *api.GraphQLError
if errors.As(err, &gqlErr) {
fmt.Printf("GraphQL error: %s\n", gqlErr.Message)
}
// ResponseError - Response parsing errors
var respErr *api.ResponseError
if errors.As(err, &respErr) {
fmt.Printf("Parse error: %s\n", respErr.Message)
}Sentinel Errors:
api.ErrNotFound // Resource not found (404)
api.ErrUnauthorized // Invalid or missing API key (401)
api.ErrAPIKeyRequired // API key not configured
api.ErrAccountIDRequired // Account ID not configuredHelper Functions:
// Check for specific error conditions
if api.IsNotFound(err) {
fmt.Println("Resource does not exist")
}
if api.IsUnauthorized(err) {
fmt.Println("Check your API key")
}Example:
app, err := client.GetApplication(12345678)
if err != nil {
if api.IsNotFound(err) {
log.Println("Application not found")
return
}
if api.IsUnauthorized(err) {
log.Fatal("Invalid API key - run 'nrq config set-api-key'")
}
log.Fatalf("API error: %v", err)
}Resolve application identifiers from multiple formats (numeric ID, Entity GUID, or application name):
// Accepts: numeric ID, Entity GUID, or application name
appID, err := client.ResolveAppID("my-application")
if err != nil {
log.Fatal(err)
}
// Now use appID with deployment or metrics APIs
deployments, err := client.ListDeployments(appID)Parse time strings in various formats for filtering:
// Relative times
t, _ := api.ParseFlexibleTime("7 days ago")
t, _ := api.ParseFlexibleTime("2 hours ago")
t, _ := api.ParseFlexibleTime("1 week ago")
// Keywords
t, _ := api.ParseFlexibleTime("now")
t, _ := api.ParseFlexibleTime("today")
t, _ := api.ParseFlexibleTime("yesterday")
// ISO8601/RFC3339
t, _ := api.ParseFlexibleTime("2025-01-14T10:00:00Z")
// Date-only (parses as start of day)
t, _ := api.ParseFlexibleTime("2025-01-14")
t, _ := api.ParseFlexibleTime("01/14/2025")Filter deployments by time range:
since, _ := api.ParseFlexibleTime("7 days ago")
until, _ := api.ParseFlexibleTime("now")
filtered := api.FilterDeploymentsByTime(deployments, since, until)Check if a string looks like an Entity GUID (useful for disambiguation):
if api.IsValidEntityGUID(input) {
// Likely a base64-encoded entity GUID
guid := api.EntityGUID(input)
appID, _ := guid.AppID()
} else if isNumeric(input) {
// Numeric app ID
appID = input
} else {
// Probably an application name
appID, _ = client.ResolveAppID(input)
}MIT License - see LICENSE for details.