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.12

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.12
File	Size	Uploaded
nsgcli-2.2.12.tar.gz	42.8 kB	Oct 2, 2026	Details

Built distribution (wheel)

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

Total release size: 96.0 kB

Release files / nsgcli-2.2.12.tar.gz

Download URL	nsgcli-2.2.12.tar.gz
Size	42.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`c6bab23698bd6a29b74140007a4a4611e8d64c8fc8269f3909ae04220f42c4bd`
BLAKE2b-256 checksum How to use checksums	`72bfb1319d3d8004a0d3f989c63caa2d93f0fa1fdf52f7f37c316a3ddbbdd2bf`
Upload date	Oct 2, 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.12-py3-none-any.whl

Download URL	nsgcli-2.2.12-py3-none-any.whl
Size	53.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1935045c249e7d8136957728d8762096e36b189c26d161ce3332eb89b18c0441`
BLAKE2b-256 checksum How to use checksums	`9dd9c0cd90d337d83f639c47fac73a0000a659c9814f97d09f777be834d10270`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`