NetSpyGlass Command Line Tools (`nsgcli`)

Command-line utilities and Python client library for NetSpyGlass Network Monitoring System (NMS).

This package provides command-line tools for querying data, checking cluster health, managing alert silences, diagnosing network agents, and working with gNMI telemetry:

nsgql: Query metrics, interface states, alerts, and topology using NsgQL (NetSpyGlass Query Language) with tabular, JSON, or time series output.
nsgcli: Interactive and batch control interface for server status, discovery queues, device management, and agent execution commands (ping, fping, traceroute).
silence: Add, update, and list active or scheduled alert silences.

Installation & Upgrade

Using `uv` (Recommended)

uv installs the CLI tools into an isolated environment and links the executables into your PATH:

# Install
uv tool install nsgcli

# Upgrade to latest version
uv tool upgrade nsgcli

Using `pip`

# Install
pip install --user nsgcli

# Upgrade
pip install --user --upgrade nsgcli

Configuration

Set default connection parameters via environment variables in your shell profile (e.g. ~/.zshrc or ~/.bashrc):

export NSG_SERVICE_URL="https://nsg.example.com:9100"
export NSG_API_TOKEN="your-api-access-token"

Alternatively, pass them explicitly on each invocation with --base-url (or -b) and --token (or -a).

Commands and Usage

1. NsgQL Queries (`nsgql`)

Run queries against the NetSpyGlass data store. Output formats include table (default ASCII table), json, list, or time_series.

# Run a query with tabular output
nsgql "select deviceId, device, address, interface, ifAddress from interfaces where address='10.0.0.1'"

# Count active alerts
nsgql "select count(key) from alerts"

# Output as JSON
nsgql -f json "select device, address from interfaces limit 5"

# Run interactively
nsgql

Corresponding Backend API:

curl -d '{"targets": [{"format":"table", "nsgql":"select count(key) from alerts"}]}' \
  -X POST -H "X-NSG-Auth-API-Token:$NSG_API_TOKEN" \
  $NSG_SERVICE_URL/v2/query/net/1/data/

2. Cluster Control & Diagnostics (`nsgcli`)

Execute commands either interactively or as single-line invocations:

# Check server and cluster version
nsgcli show version

# View cluster status
nsgcli show status

# Check discovery queue
nsgcli discovery queue

# Run ping from a specific agent
nsgcli agent ping <agent-name> 10.0.0.1

# Run fping from an agent
nsgcli agent fping <agent-name> 10.0.0.1

# Run traceroute from an agent
nsgcli agent traceroute <agent-name> 10.0.0.1

# Adjust log level on an agent
nsgcli agent set_log_level <agent-name> io.grpc DEBUG

# Start interactive shell
nsgcli

Corresponding Backend APIs:

# System status:
curl -H "X-NSG-Auth-API-Token:$NSG_API_TOKEN" \
  $NSG_SERVICE_URL/v2/nsg/cluster/net/1/status

# Agent ping:
curl -L -H "X-NSG-Auth-API-Token:$NSG_API_TOKEN" \
  "$NSG_SERVICE_URL/apiv3/net/1/exec/ping/agent/<agent-name>?address=10.0.0.1"

# Set agent log level:
curl -G -H "X-NSG-Auth-API-Token:$NSG_API_TOKEN" \
  $NSG_SERVICE_URL/v2/nsg/cluster/net/1/exec/set_log_level \
  --data-urlencode 'region=world' \
  --data-urlencode 'args=<agent-name> io.grpc DEBUG'

3. Alert Silencing (`silence`)

Manage temporary maintenance silences for alerts:

# List active and upcoming silences
silence list

# Silence all alerts for a specific device for 60 minutes
silence add --var_name='.*' --dev_id=212 --expiration=60 --reason="Scheduled maintenance"

# Silence a specific alert variable with tags
silence add --var_name='busyCpuAlert' --tags='Explicit.prod' --expiration=120

# Update expiration on an existing silence
silence update --id=8 --expiration=180

Metadata

Release files for nsgcli 2.2.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nsgcli 2.2.11
File	Size	Uploaded
nsgcli-2.2.11.tar.gz	39.6 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nsgcli 2.2.11
File	Interpreter	ABI	Platform	Reset
nsgcli-2.2.11-py3-none-any.whl 49.5 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 89.1 kB

Release files / nsgcli-2.2.11.tar.gz

Download URL	nsgcli-2.2.11.tar.gz
Size	39.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`60dabfce85952db307c89328907b7d57753a2bfcc5c6ac2eb13f58e2d241d78e`
BLAKE2b-256 checksum How to use checksums	`c0638cb0352dfc7dbbb9eacfd06244bf951a7e7fb8d150d1e3ff4aaf1be318de`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / nsgcli-2.2.11-py3-none-any.whl

Download URL	nsgcli-2.2.11-py3-none-any.whl
Size	49.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ac3376f1db9537aa5abdb7f3fcdb1707a41f9af397e96833921c61e2a860fec5`
BLAKE2b-256 checksum How to use checksums	`acd4e7edeb261d9f3be4f05e9acc31afab7e2ab1b93a905f24bd8cf9807c79e9`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`