Skip to main content
Version: 5.0.0

Command Line Interface (CLI)

Table of Contents

Options

N|Solid comes with a set of predefined endpoints for interaction and introspection that can be accessed at the command-line using the N|Solid Command Line Interface, nsolid-cli.

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/v3/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. To disable this authentication, see user authentication.

--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:

FormatDescription
milliseconds since epochValue returned from Date.now()
yyyy-mm-ddThh:mm:ssISO date
-NsN seconds since now
-NmN minutes since now
-NhN hours since now
-NdN days since now
0Now, 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

OperatorDescription
"="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

OperatorDescription
"<"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

OperatorDescription
"="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

TypeExamples
X-ranges1.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.

OptionDescription
--idThe 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.

OptionDescription
--idThe agent id or agent id prefix
--appThe NSOLID_APP value
--hostnameThe host the process is running on
--tagAn NSOLID_TAGS value (may be specified multiple times)
--typeOne of snapshot, snapshot-summary, or profile to limit the type of asset returned
--startReturn assets that were created after the specified time
--endReturn assets that were created before the specified time
--starredReturn only assets that have been starred

Usage

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

Returns a JSON stream including the following properties:

PropertyDescription
timeThe timestamp of the asset completion
assetAn asset id to use with the asset command
typeprofile, snapshot, or snapshot-summary
idThe agent id
appThe NSOLID_APP value
hostnameThe host the process is running on
tagsThe NSOLID_TAGS values
sizeThe size of the asset in bytes
compressedBoolean value representing whether the asset will be served as a gzip
pidThe operating system process id
titleThe process title
infoThe process info
metricsThe process metrics nearest the time of collection
starredBoolean value representing whether the asset is starred or not

Example JSON Result

{
"time": "2017-11-29T17:08:17.364Z",
"asset": "3011f777-b8e0-4696-ae6c-50358bce298a",
"type": "snapshot",
"id": "272470293ef95e530b1d9d072e6ed87e0c980173",
"app": "my-app-name",
"hostname": "my-computer.local",
"tags": [
"region:north",
"zone:A"
],
"size": 4288158,
"compressed": true,
"pid": 5940,
"title": "my-app-name",
"info": { ... },
"metrics": { ... },
"starred": false
}

custom

Invoke a custom command. For more information on custom commands, see Custom Commands.

OptionDescription
--idThe agent id or id prefix (required)
--nameThe name of the custom command (required)
--dataData to be sent with the command

Usage

$ nsolid-cli custom --id=[agent id] --name=verbose --data=off

Returns a JSON object with the following properties:

PropertyDescription
timeThe timestamp recorded for the event
idThe agent id
appThe NSOLID_APP value
hostnameThe host the process is running on
tagsThe NSOLID_TAGS values
resultThe result of the custom command

Example JSON Result

{
"time": "2017-12-04T00:56:28.566Z",
"id": "81535293aea1fe8c1e2f3f7518d8db3f96cf7b39",
"app": "nsolid2",
"hostname": "computer.local",
"tags": [
"localdev"
],
"result": {
"verbose": false
}
}

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 TypeDescription
license-updatedThe license data has been changed or verified with the license server
field-range-changedThe range or option set for a field has expanded or contracted
agent-packages-addedAn agent's package list has been added or updated
agent-foundA new agent has connected to the console
agent-exitAn agent has terminated

Example JSON Result

{"time":"2017-12-04T01:47:16.386Z","event":"license-updated","args":{"licensed":true}}
{"time":"2017-12-04T01:47:17.905Z","event":"field-range-changed","args":{"domain":"metrics","name":"loopsPerSecond","range":[0,22]}}
{"time":"2017-12-04T01:47:48.613Z","event":"agent-packages-added","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646}}
{"time":"2017-12-04T01:47:48.613Z","event":"agent-found","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646}}
{"time":"2017-12-04T01:47:53.087Z","event":"agent-exit","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646,"exitCode":0}}

events-historic

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

OptionDescription
--idAn agent id
--typeAn optional event type to only include
--startReturn events that occurred after the specified time
--endReturn events that occurred before the specified time
--pageAn optinal page number (events are paginated if this param is provided)
--showLimitAn optional limit of the paginated records
--orderByAn optional field to order the events (such as agentId, hostname, etc)
--orderAn 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:

PropertyDescription
publicPublic key value. publicKey in N|Solid Console configuration, and env variable NSOLID_PUBKEY for N|Solid Runtime
privatePrivate 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.

OptionDescription
--idThe full or partial agent id
--qThe query options (see above)

Usage

$ nsolid-cli info

Returns a JSON stream including the following properties:

PropertyDescription
timeMilliseconds since epoch time message was sent
idThe agent id
appThe NSOLID_APP value or name property from package.json
appVersionThe version property from package.json
hostnameThe host the process is running on
tagsThe NSOLID_TAGS values
pidOperating system process id
processStartThe time the process started
execPathPath of the executable running the application
mainThe main module used when the application started up
archThe CPU architecture
platformName of the N|Solid platform
totalMemTotal available memory in the system
cpuCoresThe number of CPU cores
cpuModelThe CPU model
versionsObject describing the versions of components used in the runtime

Example JSON Result

{
"id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
"app": "my-app-name",
"appVersion": "1.0.0",
"tags": [
"region:north",
"zone:A"
],
"pid": 14880,
"processStart": 1512335595061,
"nodeEnv": "dev",
"execPath": "/usr/bin/nsolid",
"main": "/var/my-app/app.js",
"arch": "x64",
"platform": "linux",
"hostname": "my-computer.local",
"totalMem": 8244523008,
"versions": {
"http_parser": "2.7.0",
"node": "8.10.0",
"nsolid": "3.1.0",
"v8": "6.2.414.50",
"uv": "1.19.1",
"zlib": "1.2.11",
"ares": "1.10.1-DEV",
"modules": "57",
"nghttp2": "1.25.0",
"openssl": "1.0.2n",
"icu": "60.1",
"unicode": "10.0",
"cldr": "32.0",
"tz": "2017c",
"nsolid_lib": {
"v8_profiler": "nsolid-v5.7.0-fix1",
"sodium": "nsolid-2.1.0",
"cjson": "nsolid-3.0.0",
"function_origin": "nsolid-v1.2.1",
"nan": "v2.5.1",
"cli": "v3.0.0",
"agent": "v8.0.3",
"zmq-bindings": "nsolid-2.15.4-fix1",
"zmq": "nsolid-v4.2.0-fix4",
"persistents_with_classid": "v1.1.1"
}
},
"cpuCores": 4,
"cpuModel": "Intel(R) Core(TM) i7-5600U CPU @ 2.60GHz",
"time": "2017-12-03T21:13:15.061Z"
}

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.

OptionDescription
--qThe query object (see above)

Usage

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

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

PropertyDescription
timeThe timestamp of the last metrics payload
infoThe object returned from the info command
metricsThe object returned from the metrics command

Example JSON Result

{
"time": "2017-12-04T01:17:31.299Z",
"info": { ... },
"metrics": { ... }
}

metrics

Subscribes to the metrics for a set of agents.

OptionDescription
--fieldA list of fields to include in the output. If unspecified, all fields will return
--intervalHow frequently to poll for metrics data
--qThe 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": "2017-12-04T01:23:16.163Z",
"id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
"app": "my-app-name",
"hostname": "my-computer.local",
"tags": [
"region:north",
"zone:A"
],
"activeHandles": 750,
"activeRequests": 0,
"blockInputOpCount": 0,
"blockOutputOpCount": 19424,
"cpuPercent": 0.2666424917029181,
"cpuSpeed": 2640,
"cpuSystemPercent": 0.13332124585145905,
"cpuUserPercent": 0.13332124585145905,
"ctxSwitchInvoluntaryCount": 9988,
"ctxSwitchVoluntaryCount": 1795924,
"dns99Ptile": 0,
"dnsCount": 0,
"dnsMedian": 0,
"externalMem": 734532,
"freeMem": 251301888,
"gcCount": 446,
"gcCpuPercent": 0,
"gcDurUs99Ptile": 409,
"gcDurUsMedian": 527,
"gcForcedCount": 0,
"gcFullCount": 0,
"gcMajorCount": 54,
"heapSizeLimit": 1501560832,
"heapTotal": 73269248,
"heapUsed": 60332056,
"httpClient99Ptile": 0,
"httpClientAbortCount": 0,
"httpClientCount": 0,
"httpClientMedian": 0,
"httpServer99Ptile": 0,
"httpServerAbortCount": 0,
"httpServerCount": 0,
"httpServerMedian": 0,
"ipcReceivedCount": 0,
"ipcSentCount": 0,
"load15m": 0.2333984375,
"load1m": 0.2265625,
"load5m": 0.28564453125,
"loopAvgTasks": 0,
"loopEstimatedLag": 0,
"loopIdlePercent": 100,
"loopTotalCount": 713,
"loopsPerSecond": 0,
"pageFaultHardCount": 0,
"pageFaultSoftCount": 132206,
"rss": 138301440,
"signalCount": 0,
"swapCount": 0,
"systemUptime": 23006,
"title": "node",
"totalAvailableSize": 1437491784,
"totalHeapSizeExecutable": 5242880,
"totalPhysicalSize": 72644376,
"uptime": 15000.85,
"user": "appuser",
"vulns": 1
}

metrics-historic

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

OptionDescription
--fieldA list of fields to include in the output. If unspecified, all fields will return
--qThe query set (see above)
--startThe start of the time range
--endThe end of the time range
--seriesThe aggregation level of the data. Can be raw, 1m, or 1h. Defaults to raw

Usage

$ nsolid-cli metrics-historic --start=-5m --end=-1m

packages

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

OptionDescription
--idThe full agent id or prefix

Usage

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

Returns a JSON object with the following properties:

PropertyDescription
idThe agent id
timeThe timestamp of the message
appThe NSOLID_APP value
packagesAn array of package objects with details about the package and its dependencies
vulnerabilitiesAn object with vulnerability details

Example JSON Result

{
"id": "a40827afbc3620e40887d6774249c321848d54f6",
"time": "2017-12-04T01:26:12.514Z",
"packages": [
{
"name": "my-app-name",
"version": "1.0.0",
"path": "/var/my-app",
"main": "app.js",
"dependencies": [
"node_modules/debug",
"node_modules/minimist",
"node_modules/split"
],
"dependents": [],
"vulns": []
},
{
"name": "debug",
"version": "2.2.0",
"path": "/var/my-app/node_modules/debug",
"main": "./node.js",
"dependencies": [
"../ms"
],
"dependents": [
"../.."
],
"vulns": [
"npm:debug:20170905"
]
},
{
"name": "minimist",
"version": "1.2.0",
"path": "/var/my-app/node_modules/minimist",
"main": "index.js",
"dependencies": [],
"dependents": [
"../.."
],
"vulns": []
},
{
"name": "ms",
"version": "0.7.1",
"path": "/var/my-app/node_modules/ms",
"main": "./index",
"dependencies": [],
"dependents": [
"../debug"
],
"vulns": [
"npm:ms:20170412"
]
},
{
"name": "split",
"version": "1.0.0",
"path": "/var/my-app/node_modules/split",
"dependencies": [
"../through"
],
"dependents": [
"../.."
],
"vulns": []
},
{
"name": "through",
"version": "2.3.8",
"path": "/var/my-app/node_modules/through",
"main": "index.js",
"dependencies": [],
"dependents": [
"../split"
],
"vulns": []
}
],
"vulnerabilities": [
{
"package": "debug",
"title": "Regular Expression Denial of Service (ReDoS)",
"published": "2017-09-26T03:55:05.106Z",
"credit": [
"Cristian-Alexandru Staicu"
],
"id": "npm:debug:20170905",
"ids": {
"NSP": 534,
"CWE": [
"CWE-400"
],
"CVE": [],
"ALTERNATIVE": [
"SNYK-JS-DEBUG-10762"
]
},
"vulnerable": "<2.6.9 || >=3.0.0 <3.1.0",
"severity": "low",
"description": " ... ",
"nsolidMetaData": {
"hidden": false
},
"packages": [
"/var/my-app/node_modules/debug"
],
"depsChains": [
[
"nsolid-dev-demo@1.0.0",
"debug@2.2.0"
]
],
"topLevel": 1
},
{
"package": "ms",
"title": "Regular Expression Denial of Service (ReDoS)",
"published": "2017-05-15T06:02:45.497Z",
"credit": [
"Snyk Security Research Team"
],
"id": "npm:ms:20170412",
"ids": {
"CWE": [
"CWE-400"
],
"CVE": [],
"ALTERNATIVE": [
"SNYK-JS-MS-10509"
]
},
"vulnerable": "<2.0.0",
"severity": "low",
"description": " ... ",
"nsolidMetaData": {
"hidden": false
},
"packages": [
"/var/my-app/node_modules/ms"
],
"depsChains": [
[
"nsolid-dev-demo@1.0.0",
"debug@2.2.0",
"ms@0.7.1"
]
],
"topLevel": 1
}
]
}

profile

Generates a V8 CPU profile of the specified process.

OptionDescription
--idThe agent id (required)
--durationDuration of profile in seconds. Default is 10 minutes

Usage

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

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

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

snapshot

Generates a V8 heap snapshot of the specified process.

OptionDescription
--idThe 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

Note: 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.

OptionDescription
--idThe full agent id or prefix

Usage

$ nsolid-cli startup-times

Returns a JSON stream including the following properties:

PropertyDescription
timeMilliseconds since epoch time message was sent
idThe agent id
appThe NSOLID_APP value
hostnameThe host the process is running on
initialized_nodeAn array of two integers. The time it took to initialize the Node internals, reported as [seconds, nanoseconds]
initialized_v8An array of two integers. The time it took to initialize the V8 engine, reported as [seconds, nanoseconds]
loaded_environmentAn array of two integers. The time it took to complete all initialization, which includes running some of Node's internal JavaScript code, and your main module's top-level code, reported as [seconds, nanoseconds]

Example JSON Result

{
"loaded_environment": [
0,
322526338
],
"initialized_node": [
0,
120919
],
"initialized_v8": [
0,
240910
],
"id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
"time": "2017-12-04T01:32:30.042Z",
"tags": [
"region:north",
"zone:A"
],
"app": "my-app-name",
"hostname": "my-computer.local"
}

Additional timers can be added to your application with custom lifecycle events.

vulnerabilities

Returns known security vulnerabilities for all processes.

Usage

$ nsolid-cli vulnerabilities

Returns a JSON object representing all current known vulnerabilities.

PropertyDescription
timeMessage timestamp
vulnerabilitiesAn array of vulnerability objects

Example JSON Result

{
"time": "2017-12-04T01:34:54.805Z",
"vulnerabilities": [
{
"report": {
"package": "ms",
"title": "Regular Expression Denial of Service (DoS)",
"published": "2015-11-06T02:09:36.187Z",
"credit": [
"Adam Baldwin"
],
"id": "npm:ms:20151024",
"ids": {
"CWE": [
"CWE-400"
],
"CVE": [
"CVE-2015-8315"
],
"NSP": 46,
"ALTERNATIVE": [
"SNYK-JS-MS-10064"
]
},
"vulnerable": "<=0.7.0",
"severity": "medium",
"description": " ... ",
"nsolidMetaData": {
"hidden": false
}
},
"processes": [
{
"id": "e1c17bc36d7a9cc76ead259ace0307d4b9705646",
"app": "my-app-name",
"tags": [
"region:north",
"zone:A"
],
"hostname": "my-computer.local",
"topLevel": 1,
"depChains": [
[
"ms@0.7.0"
]
]
}
...
]
},
...
]
}

query

Subscribe to matching agent data on an interval.

OptionDescription
--fieldList of fields to request. All fields returned if not specified
--intervalNumber of seconds before returning next current object (default: 1)
--qThe query filter options (see above)

Usage

$ nsolid-cli query --q id=5

Returns newline delimited JSON objects with framing objects.

Framing TypeDescription
startThe query stream start frame
interval-startThe start of the records for this interval
agent-enterAn agent entry
summarySummary data about the entire (unfiltered) data set
interval-endThe last record for this interval frame

Example JSON Result

{"time":"2017-12-04T01:42:29.502Z","type":"start"}
{"time":"2017-12-04T01:42:29.502Z","type":"interval-start"}
{"time":"2017-12-04T01:42:29.502Z","type":"agent-enter","id":"5dd6f7a940bfc3633cc3ffc82332640d51ce5112","info":{ ... },"metrics":{ ... }
{"time":"2017-12-04T01:42:29.502Z","type":"summary","totalAgents":9}
{"time":"2017-12-04T01:42:29.502Z","type":"interval-end"}

summary

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

OptionDescription
--qThe query options (see above)

Usage

$ nsolid-cli summary

Example JSON Result

{
"time": "2017-12-04T02:12:02.506Z",
"processes": 9,
"apps": {
"my-app-name": 5,
"api-server": 1,
"web": 1,
"batch-service": 2
},
"tags": {
"region:north": 4,
"zone:A": 5,
"region:south": 5,
"zone:B": 2,
"zone:C": 2
},
"rss": 693153792,
"cpu": 3.4667812728278924,
"node": {
"8.9.1": 9
},
"nsolid": {
"3.0.0": 9
},
"packages": 552,
"vulnerabilities": {
"npm:ms:20170412": 4,
"npm:qs:20140806": 2,
},
"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.

OptionDescription
--itemCould 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.

OptionDescription
--itemCould be one or a list of items to export (see example)
--actionAppend to or clean previous settings (see example)

Usage

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