Using the N|Solid CLI

The N|Solid Runtime ships with a cli tool that can directly communicate with the N|Solid Console Server's internal API, allowing you to automate some of behaviors that you might perform in the N|Solid Pro interface.

important

In order to use it with your SaaS Console, please contact support for us to enable this feature and provide you a secure access token for your SaaS Console Server's API endpoint.

Options

The N|Solid CLI tool mirrors the Console's API schema. Many options are documented below. For commands not documented here, consult your Console's API Docs at http://localhost:6753/api/v4/api-docs (replace localhost:6753 with your Console server's address.)

To see a list of help information for nsolid-cli, use the -h option:

$ nsolid-cli -h

The output of the nsolid-cli commands, unless otherwise noted, is line-delimited JSON (each line is separated by a newline delimiter \n). The output shown in the examples below is expanded for readability.

--auth

If your Console is running with authentication enabled, you will need to configure an administrative access token to allow nsolid-cli to be permitted to access it. This can be set with the NSOLID_CONSOLE_AUTH_ADMIN_TOKEN environment variable or the corresponding config file setting to a secure value value. Once set, you can pass this value to nsolid-cli using the --auth argument.

Example:

$ nsolid-cli --remote=https://YOUR_SAAS_URL.saas.nodesource.io --auth="YOUR_TOKEN_HERE" summary

--attach

For the specific case of importing settings from a configuration file .nsconfig, you can use this option to read the contents from the file in the filesystem.

--start and --end options

For commands that take --start and --end options, you can pass the following formats for the date/time value:

Format	Description
milliseconds since epoch	Value returned from Date.now()
yyyy-mm-ddThh:mm:ss	ISO date
-Ns	N seconds since now
-Nm	N minutes since now
-Nh	N hours since now
-Nd	N days since now
0	Now, when used with the --end option

--q option

Some commands take a --q parameter followed by a query filter expression. Only results matching all query filter terms will be returned.

A filter term is a string with no spaces separating the values.

"field+operator+value"

The field may be any field from info or metrics, or vulns, vuln, or package. See the output of those commands to see what options exist for the field portion of the query.

The operators for each field type are described below.

The value can be a single value or a list of values separated by ,. The term will evaluate to true if the field and operator match any of the specified values. Values may escape any character by preceding it with the % character. In practice, the only characters that need to be escaped are %, (space), and ,.

A query filter expression is a list of filter terms, separated by space characters.

Here is an example showing the list command being passed the --q flag with a query filter expression that has two filter terms:

$ nsolid-cli list --q "vulns>=2 package=express"

String Operators

Operator	Description
"="	Evaluates to true if the field value is equal to any value in the expression
"!="	Evaluates to true if the field value is not equal to any value in the expression
"~"	Evaluates to true if the field value wild-card matches any value in the expression
"!~"	Evaluates to true if the field value does not wild-card match any value in the expression

Note that multiple string values may be specified in the expression, separated by commas.

Number Operators

Operator	Description
"<"	Evaluates to true if the field value is less than the value in the expression
"<="	Evaluates to true if the field value is less than or equal to the value in the expression
">"	Evaluates to true if the field value is greater than the value in the expression
">="	Evaluates to true if the field value is greater than or equal to the value in the expression

Package Operators

Operator	Description
"="	Evaluates to true if the field value equals the value in the expression
"!="	Evaluates to true if the field value does not equal the value in the expression
"<"	Evaluates to true if the field value is less than the value in the expression
"<=""	Evaluates to true if the field value is less than or equal to the value in the expression
">"	Evaluates to true if the field value is greater than the value in the expression
">="	Evaluates to true if the field value is greater than or equal to the value in the expression

A value for packages fields is either package name or {package name}@{simple-semver-range}, where a simple semver range is one of:

Semver Ranges

Type	Examples
X-ranges	1.2.3, 1.2, 1.2.x, 1.x, 1.2.*, etc.
Tilde ranges	~1.2.3, ~1.2, etc.
Caret ranges	^1.2.3, ^1.2, etc.

Using the < and > operators will do a semver range check comparing the versions.

asset

Download an asset.

Option	Description
--id	The asset id (required)

Usage

$ nsolid-cli asset --id 217040c0-02d1-4956-8648-7fb84b78c65e > my.heapsnapshot

Asset IDs are available via the assets command described below. The asset file itself will be written to stdout. The N|Solid CLI tool will automatically manage decompression if the asset is compressed.

assets

Lists the assets (CPU profiles and heap snapshots) that are currently available for download.

Option	Description
--id	The agent id or agent id prefix
--app	The NSOLID_APP value
--hostname	The host the process is running on
--tag	An NSOLID_TAGS value (may be specified multiple times)
--type	One of snapshot, snapshot-summary, or profile to limit the type of asset returned
--start	Return assets that were created after the specified time
--end	Return assets that were created before the specified time
--starred	Return only assets that have been starred

Usage

$ nsolid-cli assets --app my-app-name --type snapshot

Returns a JSON stream including the following properties:

Property	Description
threadId	The integer id of this thread. 0 = main thread.
time	The timestamp of the asset completion
asset	An asset id to use with the asset command
type	profile, snapshot, or snapshot-summary
id	The agent id
reason	How the profile was triggered. User for manual or View for triggered collection.
app	The NSOLID_APP value
hostname	The host the process is running on
tags	The NSOLID_TAGS values
duration	The duration in milliseconds of the profile contents.
size	The size of the asset in bytes
compressed	Boolean value representing whether the asset will be served as a gzip
deleteSoon	A flag as to whether the asset is slated for being deleted as part of automated housekeeping soon.
pid	The operating system process id
title	The process title
info	The process info
metrics	The process metrics nearest the time of collection
visualization	The type of visualization, e.g. 'flamegraph'
sourceMap	Boolean value representing whether there is a sourcemap for this profile.
starred	Boolean value representing whether the asset is starred or not

Example JSON Result

{
  "threadId": 0,
  "time": "2024-05-29T16:37:19.378Z",
  "asset": "abdbde9c-bcf8-4e62-98cb-b81a076bd5ec",
  "type": "profile",
  "id": "e722dbdab1744400e7acfeafba9e86001b9da5b6",
  "reason": "User",
  "app": "webserver",
  "hostname": "EC2AMAZ-ED516RQ",
  "tags": [],
  "duration": 5029,
  "size": 0,
  "compressed": true,
  "deleteSoon": 0,
  "pid": 5296,
  "title": "Administrator: NSolid Command Prompt - nsolid",
  "info": { ... },
  "metrics": { ... },
  "visualization": "flamegraph",
  "sourceMap": false,
  "starred": false
  }
}

custom

Invoke a custom command. For more information on custom commands, see How-To Guide.

Option	Description
--id	The agent id or id prefix (required)
--name	The name of the custom command (required)
--data	Data to be sent with the command

Usage

# calls nsolid.on('verbose', fn) in your application if present
$ nsolid-cli custom --id=[agent id] --name=verbose --data=off

Returns a JSON object with the following properties:

Property	Description
result	The result of the custom command--the contents of request.reply(result) in the handler.
time	The timestamp recorded for the event
id	The agent id
app	The NSOLID_APP value
hostname	The host the process is running on
tags	The NSOLID_TAGS values

Example JSON Result

{
  "result": {
    "ok": true
  },
  "id": "5bc4a84c62710b007f4ed6f96d00570079c60920",
  "app": "example",
  "hostname": "anoxia",
  "tags": [],
  "time": 1717010944178
}

events

Subscribe to the event stream, which emits a wide array of event types and metadata.

Usage

$ nsolid-cli events

There are many types of events, and more are added all the time. Some of the primary types are described below.

Event Type	Description
license-updated	The license data has been changed or verified with the license server
field-range-changed	The range or option set for a field has expanded or contracted
agent-packages-added	An agent's package list has been added or updated
agent-found	A new agent has connected to the console
agent-exit	An agent has terminated

Example JSON Result

{"time":"2024-05-29T19:41:12.389Z","event":"field-range-changed","args":{"domain":"metrics","name":"cpuPercent","range":[0,110]}}
{"time":"2024-05-29T19:41:12.389Z","event":"field-range-changed","args":{"domain":"metrics","name":"heapTotal","range":[0,1300000000]}}
{"time":"2024-05-29T19:41:12.389Z","event":"field-range-changed","args":{"domain":"metrics","name":"loopEstimatedLag","range":[0,4000]}}
...

events-historic

Extract the events from a range of time in the past.

Option	Description
--id	An agent id
--type	An optional event type to only include
--start	Return events that occurred after the specified time
--end	Return events that occurred before the specified time
--page	An optinal page number (events are paginated if this param is provided)
--showLimit	An optional limit of the paginated records
--orderBy	An optional field to order the events (such as agentId, hostname, etc)
--order	An optional order parameter (asc or desc)

Usage

$ nsolid-cli events-historic --start="-2h" --end="-1h"

generate-keypair

Returns a randomly generated keypair suitable for use in the N|Solid Console socket configuration. If your N|Solid Console instance is running on an untrusted network, it is recommended that you generate and use new keys.

Usage

$ nsolid-cli generate-keypair

Returns a JSON object with the following properties:

Property	Description
public	Public key value. publicKey in N|Solid Console configuration, and env variable NSOLID_PUBKEY for N|Solid Runtime
private	Private key value. privateKey in N|Solid Console configuration

Example JSON Result

{
  "public": "[t&m}{EZH7=HR(IW:+Ttk:=r.Y$:CP+-Q&5L?2N!",
  "private": "4QZof={^Pman?I?mB0o!]%z/{Jlu6:mJfl[Ms@[^"
}

info

Returns objects which contain static information about processes and the hosts they are running on.

Option	Description
--id	The full or partial agent id
--q	The query options (see above)

Usage

$ nsolid-cli info

Returns a JSON stream including the following properties:

Property	Description
time	Milliseconds since epoch time message was sent
id	The agent id
app	The NSOLID_APP value or name property from package.json
appVersion	The version property from package.json
hostname	The host the process is running on
tags	The NSOLID_TAGS values
pid	Operating system process id
processStart	The time the process started
execPath	Path of the executable running the application
main	The main module used when the application started up
arch	The CPU architecture
platform	Name of the N|Solid platform
totalMem	Total available memory in the system
cpuCores	The number of CPU cores
cpuModel	The CPU model
versions	Object describing the versions of components used in the runtime

Example JSON Result

{
  "app": "webserver",
  "appVersion": "5.3.0",
  "arch": "x64",
  "cpuCores": 4,
  "cpuModel": "Intel(R) Xeon(R) Platinum 8488C",
  "execPath": "/bin/nsolid",
  "hostname": "02b3ed82-6bac-49a0-ba1b-878cd93745ae-7d58498dc9-8z6km",
  "id": "44c58a6b7c607c00d58fc184f6dab60080d16cd4",
  "main": "/usr/src/app/webserver",
  "nodeEnv": "production",
  "pid": 7,
  "platform": "linux",
  "processStart": 1716993070545,
  "tags": [],
  "totalMem": 16467304448,
  "versions": { ... },
  "time": "2024-05-29T14:31:10.545Z"
}
...

list

Returns an array of all available matching N|Solid processes, along with their most recent info and metrics data. The command ls is an alias for this command.

Option	Description
--q	The query object (see above)

Usage

$ nsolid-cli list --q id=5dd6

Returns newline delimited JSON objects where each row includes the following properties:

Property	Description
time	The timestamp of the last metrics payload
info	The object returned from the info command
metrics	The object returned from the metrics command

Example JSON Result

{
  "time": "2024-05-29T19:46:46.103Z",
  "info": {
    "time": "2024-05-29T19:46:46.103Z",
    "id": "44c58a6b7c607c00d58fc184f6dab60080d16cd4",
    "app": "webserver",
    "hostname": "02b3ed82-6bac-49a0-ba1b-878cd93745ae-7d58498dc9-8z6km",
    "tags": [],
    "appVersion": "5.3.0",
    "arch": "x64",
    "cpuCores": 4,
    "cpuModel": "Intel(R) Xeon(R) Platinum 8488C",
    "execPath": "/bin/nsolid",
    "main": "/usr/src/app/webserver",
    "nodeEnv": "production",
    "pid": 7,
    "platform": "linux",
    "processStart": 1716993070545,
    "totalMem": 16467304448,
    "versions": { ... }
  },
  "metrics": { ... }
}

metrics

Subscribes to the metrics for a set of agents.

Option	Description
--field	A list of fields to include in the output. If unspecified, all fields will return
--interval	How frequently to poll for metrics data
--q	The query set (see above)

Usage

$ nsolid-cli metrics

Consult the Metrics in Detail section for complete details on the metrics available.

Example JSON Result

{"time":"2024-05-29T19:48:37.249Z","id":"44c58a6b7c607c00d58fc184f6dab60080d16cd4","app":"webserver","hostname":"02b3ed82-6bac-49a0-ba1b-878cd93745ae-7d58498dc9-8z6km","tags":[],"activeHandles":8,"activeRequests":0,"blockInputOpCount":18344,"blockOutputOpCount":86448,"cpu":1.0176217699999999,"cpuPercent":101.762177,"cpuSystemPercent":2.803665,"cpuUserPercent":98.958512,"ctxSwitchInvoluntaryCount":390983,"ctxSwitchVoluntaryCount":4070346,"delay":8768639.573029,"dns99Ptile":0,"dnsCount":496,"dnsMedian":0,"eventsProcessed":7202045,"eventsWaiting":7184302,"externalMem":67914068,"freeMem":9133502464,"fsHandlesClosedCount":6,"fsHandlesOpenedCount":6,"gcCount":381851,"gcDurUs99Ptile":13605,"gcDurUsMedian":1485,"gcForcedCount":0,"gcFullCount":0,"gcMajorCount":3030,"heapSizeLimit":2197815296,"heapTotal":1149370368,"heapUsed":1102212104,"httpClient99Ptile":0,"httpClientAbortCount":0,"httpClientCount":3045,"httpClientMedian":0,"httpConnections":5,"httpServer99Ptile":0,"httpServerAbortCount":1,"httpServerCount":43,"httpServerMedian":0,"ipcReceivedCount":0,"ipcSentCount":0,"load15m":1.31,"load1m":0.83,"load5m":1.27,"loopAvgTasks":0,"loopEstimatedLag":6842.682142,"loopIdlePercent":0,"loopIdleTime":9693339671845,"loopIterWithEvents":7180420,"loopIterations":7254748,"loopTotalCount":7254748,"loopUtilization":1,"mallocedMemory":1081456,"numberOfDetachedContexts":0,"numberOfNativeContexts":1,"pageFaultHardCount":8,"pageFaultSoftCount":124529579,"peakMallocedMemory":37345928,"pipeServerCreatedCount":0,"pipeServerDestroyedCount":0,"pipeSocketCreatedCount":2,"pipeSocketDestroyedCount":0,"processingDelay":22285260577,"promiseCreatedCount":0,"promiseResolvedCount":0,"providerDelay":8746354312452,"res15m":0.712438,"res1m":0.746145,"res5m":0.720961,"res5s":1.022003,"rss":1424875520,"signalCount":0,"swapCount":0,"systemUptime":8234722,"tcpServerCreatedCount":1,"tcpServerDestroyedCount":0,"tcpSocketCreatedCount":499,"tcpSocketDestroyedCount":494,"threadId":0,"threadName":"","threads":[1,2,0],"threadsName":{"0":"","1":"","2":""},"timestamp":1717012116412,"title":"webserver","totalAvailableSize":1076845368,"totalHeapSizeExecutable":4612096,"totalPhysicalSize":1149161472,"udpSocketCreatedCount":0,"udpSocketDestroyedCount":0,"uptime":19045,"user":"ns","vulns":17}
}
...

metrics-historic

Retrieve metrics records over a historical time range. Records match the metrics command output.

Option	Description
--field	A list of fields to include in the output. If unspecified, all fields will return
--q	The query set (see above)
--start	The start of the time range
--end	The end of the time range
--series	The aggregation level of the data. Can be raw, 1m, or 1h. Defaults to raw

Usage

$ nsolid-cli metrics-historic --start="-2m" --end="-1m"

packages

Returns a list of packages and modules available in the specified process.

Option	Description
--id	The full agent id or prefix

Usage

$ nsolid-cli packages --id=[agent id]

Returns a JSON object with the following properties:

Property	Description
id	The agent id
time	The timestamp of the message
app	The NSOLID_APP value
packages	An array of package objects with details about the package and its dependencies
vulnerabilities	An object with vulnerability details

profile

Generates a V8 CPU profile of the specified process.

Option	Description
--id	The agent id (required)
--duration	Duration of profile in seconds. Default is 10 minutes

Usage

$ nsolid-cli profile --id=[agent id] --duration=10 > my.cpuprofile

Once the profile file has been created, it can be opened using Chrome’s Development Tool’s CPU Profile Debugging Tool.

tip

To load the file, Chrome requires that the generated file have the extension .cpuprofile.

snapshot

Generates a V8 heap snapshot of the specified process.

Option	Description
--id	The agent id (required)

Usage

$ nsolid-cli snapshot --id=[agent id] > my.heapsnapshot

Once the snapshot file has been created, it can be opened using Chrome’s Development Tool’s heap snapshot browser

tip

To load the file, Chrome requires that the generated file have the extension .heapsnapshot.

startup-times

Lists the time to reach certain process lifecycle startup phases from initial process execution.

Option	Description
--id	The full agent id or prefix

Usage

$ nsolid-cli startup-times

Returns a JSON stream including the recorded startup times. See the JS API for more information about nsolid.startupTimes and how to customize the results.

Example JSON Result

{
  "bootstrap_complete": [0, 16133046],
  "initialized_node": [0, 348150],
  "initialized_v8": [0, 2948542],
  "loaded_environment": [0, 7952192],
  "loop_start": [0, 28983685],
  "timeOrigin": [0, 0],
  "timeOriginTimestamp": [1572676, 809463407],
  "id": "01476b6496aa530063f92c5e4c5da800cf5685ae",
  "time": "2024-05-29T19:59:29.974Z",
  "tags": [],
  "app": "example",
  "hostname": "anoxia"
}

vulnerabilities

Returns known security vulnerabilities for all processes.

Usage

$ nsolid-cli vulnerabilities

Returns a JSON object representing all current known vulnerabilities.

Property	Description
time	Message timestamp
vulnerabilities	An array of vulnerability objects

Example JSON Result

{
  "time": "2024-05-29T20:02:39.924Z",
  "lastUpdated": "2024-05-29T19:35:21.257Z",
  "vulnerabilities": [
    {
      "report": {
        "package": "d3-color",
        "title": "d3-color vulnerable to ReDoS",
        "published": "2022-09-29T14:12:55Z",
        "credit": [
          "UNSPECIFIED"
        ],
        "id": "GHSA-36jr-mh4h-2g58",
        "ids": {...},
        "vulnerable": "< 3.1.0",
        "severity": "high",
        "description": "The d3-color module provides ...",
        "nsolidMetaData": {
          "hidden": false
        }
      },
      "processes": [
        {
          "id": "24472c3ed21920005805bbd0770890003655b818",
          "app": "e51e6006-6589-49f0-aef5-0982b6f0060d",
          "tags": [],
          "hostname": "e51e6006-6589-49f0-aef5-0982b6f0060d-55964b5d4-855qv",
          "topLevel": 1,
          "depChains": [
            [
              "d3-color@2.0.0"
            ]
          ]
        },
        { ... }
      ],
      "processCount": 5
    }
  ],
  "vulnerabilityCount": 1
}

query

Subscribe to matching agent data on an interval.

Option	Description
--field	List of fields to request. All fields returned if not specified
--interval	Number of seconds before returning next current object (default: 1)
--q	The query filter options (see above)

Usage

$ nsolid-cli query --q id=5

Returns newline delimited JSON objects with framing objects.

Framing Type	Description
start	The query stream start frame
interval-start	The start of the records for this interval
agent-enter	An agent entry
summary	Summary data about the entire (unfiltered) data set
interval-end	The last record for this interval frame

Example JSON Result

{"time":"2024-05-29T20:08:19.064Z","type":"start"}
{"time":"2024-05-29T20:08:19.065Z","type":"interval-start"}
{"time":"2024-05-29T20:08:19.065Z","type":"agent-enter","id":"24472c3ed21920005805bbd0770890003655b818","info":{ ... },"metrics":{ ... }}
{"time":"2024-05-29T20:08:19.065Z","type":"summary","matchingAgents":1,"totalAgents":1}
{"time":"2024-05-29T20:08:19.065Z","type":"interval-end"}
{"time":"2024-05-29T20:08:20.066Z","type":"interval-start"}
{"time":"2024-05-29T20:08:20.066Z","type":"metrics","id":"24472c3ed21920005805bbd0770890003655b818","metrics":{ ... }}
{"time":"2024-05-29T20:08:20.066Z","type":"summary","matchingAgents":1,"totalAgents":1}
{"time":"2024-05-29T20:08:20.066Z","type":"interval-end"}

summary

Pull a summary of all connected N|Solid processes. Reports counts of matched properties or resources.

Option	Description
--q	The query options (see above)

Usage

$ nsolid-cli summary

Example JSON Result

{
  "time": "2024-05-29T20:12:19.555Z",
  "processes": 8,
  "apps": {
    "webserver": 5,
    "portal": 2,
    "demo": 1
  },
  "tags": {},
  "rss": 2808512512,
  "cpu": 196.852483,
  "node": {
    "20.12.2": 5,
    "20.11.1": 1,
    "20.13.1": 2
  },
  "nsolid": {
    "5.2.0": 5,
    "5.0.5": 1,
    "5.2.2": 2
  },
  "packages": 3945,
  "vulnerabilities": {
    "GHSA-36jr-mh4h-2g58": 1
  },
  "hiddenVulnerabilities": {}
}

export-settings

Pull a JSON object with one or many settings configuration to backup or import later. The only settings available to export are: integrations, savedViews and notifications.

Option	Description
--item	Could be one or a list of items to export (see example)

Usage

$ nsolid-cli export-settings --item integrations,savedViews,notifications

Example JSON Result

{
  "_metadata": {
    "_timestamp": "",
  },
  "integrations": {},
  "notifications": {},
  "savedViews": {}
}

import-settings

Apply a previously backup/exported settings. The only settings available to import are: integrations, savedViews and notifications.

Option	Description
--item	Could be one or a list of items to export (see example)
--action	Append to or clean previous settings (see example)

Usage

$ nsolid-cli import-settings --item integrations --action clean --attach backup.nsconfig