This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent has shell access, it can use the New Relic CLI to search data New Relic collects about software while investigating a code change or production issue. The CLI is New Relic’s command-line tool for tasks such as running NRQL queries, inspecting entities, and managing workloads. NRQL is New Relic’s language for searching telemetry New Relic collects about software, including transaction records.
The CLI runs commands from your development environment and sends requests to New Relic. It is a general-purpose tool, not a coding-agent-specific interface. You choose the New Relic account and permissions through a profile, a saved set of connection details, then give the agent a specific task, such as checking transaction counts. The New Relic CLI documentation covers the command set and configuration.
Install and configure the CLI
On macOS with Homebrew, install the CLI with:
brew install newrelic-cli
For other installation methods, use New Relic’s CLI setup instructions.
Before an agent runs New Relic commands, create a CLI profile with the newrelic profile add command. The profile stores the connection details the CLI uses. It needs an API key and the region of your New Relic account (us, eu or jp). New Relic's setup guide uses a user key for this:
newrelic profile add --profile agent --apiKey YOUR_USER_KEY --region us
newrelic profile default --profile agent
Run profile setup yourself; do not put the API key in an agent prompt or a code file. Choose an account and API key with permissions for the tasks you assign the agent.
The agent also needs access to the installed newrelic executable and to the profile you created. Each user key is tied to a specific user, and New Relic warns that someone with that key can view your New Relic data and make changes to the account. An agent that can run the CLI with that profile has the same access.
Query transaction data
You can ask the agent to check how many transactions New Relic recorded recently with a read-only query. For example:
newrelic nrql query --query 'SELECT count(*) FROM Transaction SINCE 1 hour ago' --accountId <ACCOUNT_ID>
Replace <ACCOUNT_ID> with the numeric ID of the New Relic account you want to query. The nrql query command requires both --query and --accountId. This query counts Transaction records from the past hour. The command sends a query to New Relic and leaves telemetry unchanged. It also leaves configuration and application code unchanged.
By default, the CLI returns JSON, a format that lets the agent inspect the results as structured data. The global --format option also accepts Text and YAML. Ask the agent to report the returned count and note whether the query returned no matching data or an error. Do not ask it to invent an explanation for a low count: the query measures recorded transactions, and the result alone does not establish why the count is low.
Give the agent a bounded task
Tell the agent which account and query to use and what to report, without sharing credentials:
Use the configured New Relic CLI profile to run a read-only NRQL query for the transaction count from the last hour in account
<ACCOUNT_ID>. Report the count and any command error. Do not change New Relic settings or write files.
When the agent runs the command, it sends a request to New Relic. The shell command itself does not modify local project files. The CLI also includes commands that manage entity tags, workloads, and deployment markers, so a shell-enabled agent could make service-side changes if you ask it to use those commands. Keep the example limited to the nrql query command when you only need evidence.