`ngsw` command line¶

ngsw exposes the whole library from a shell: reads, writes, model discovery, state capture, and the mock switch daemons.

ngsw models                                              # no switch needed
ngsw --host 10.1.5.22 --model gsm7252ps --community public ports
ngsw --switch core vlans --json
ngsw --switch core --backend http vlans

Selecting a switch¶

Two ways; pick exactly one:

From an inventory — --switch NAME together with --config <inventory.toml>; --switch without --config is an error. Credentials and protected ports come with the entry. See Inventories and credentials.

Ad hoc — --host HOST --model KEY together, with credentials from flags, environment variables, or an interactive prompt.

Credential precedence is flag → environment variable → inventory → prompt, and the prompt is only reached for a credential the chosen backend actually needs: a Plus switch reached over NSDP is never asked for an SNMP community.

Choosing the protocol¶

Output¶

Human-readable tables by default; --json emits machine-readable JSON. -v/--verbose prints tracebacks instead of one-line error messages.

Write safety¶

Every disruptive subcommand carries the same three gates:

--dry-run: Print the operation that would be sent, and send nothing. The description is at facade granularity — method, arguments, host — rather than a re-encoded SNMP SET or HTTP form, so it cannot drift from what would really happen.
-y / --yes: Skip the interactive confirmation.
--force: Override protected_ports and the other force gates.

ngsw --switch core port 7 down --dry-run
ngsw --switch core vlan create 4001 throwaway --yes
ngsw --switch core vlan set 4001 7 tagged --force

Exit status is 0 on success and non-zero on error; a refused operation is an error, not a silent no-op.

Complete reference¶

Generated from the parser in src/netgear_switch/cli/main.py, so it lists every command and option the installed version actually accepts.

Query and control Netgear switches over the SyncSwitch facade.

usage: ngsw [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
            [--model KEY] [--community STR] [--write-community STR]
            [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
            [--json] [-v]
            {models,ports,stats,vlans,pvids,lldp,macs,sensors,users,services,show,identify,nsdp-device,poe,port,describe,speed,flow-control,cycle-poe,clear-poe-fault,upload-certificate,upload-certificate-scp,pvid,vlan,ip,hostname,syslog,capture,serve}
            ...

Positional Arguments¶

command: Possible choices: models, ports, stats, vlans, pvids, lldp, macs, sensors, users, services, show, identify, nsdp-device, poe, port, describe, speed, flow-control, cycle-poe, clear-poe-fault, upload-certificate, upload-certificate-scp, pvid, vlan, ip, hostname, syslog, capture, serve

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

run the operation over EXACTLY this backend (snmp/nsdp/http/ssh/telnet/console) instead of the model’s default; the operation fails if that backend cannot serve it – it is never re-routed to another protocol

--json

emit machine-readable JSON output

Default: False

-v, --verbose

print tracebacks on error

Default: False

Sub-commands¶

models¶

list the known switch models

ngsw models [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
            [--model KEY] [--community STR] [--write-community STR]
            [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
            [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

ports¶

show port status

ngsw ports [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
           [--model KEY] [--community STR] [--write-community STR]
           [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
           [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

stats¶

show port RX/TX counters

ngsw stats [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
           [--model KEY] [--community STR] [--write-community STR]
           [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
           [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

vlans¶

show VLANs

ngsw vlans [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
           [--model KEY] [--community STR] [--write-community STR]
           [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
           [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

pvids¶

show per-port PVIDs

ngsw pvids [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
           [--model KEY] [--community STR] [--write-community STR]
           [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
           [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

lldp¶

show LLDP neighbours

ngsw lldp [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
          [--model KEY] [--community STR] [--write-community STR]
          [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
          [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

macs¶

show the MAC/FDB table

ngsw macs [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
          [--model KEY] [--community STR] [--write-community STR]
          [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
          [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

sensors¶

show sensors

ngsw sensors [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
             [--model KEY] [--community STR] [--write-community STR]
             [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
             [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

users¶

show local login accounts

ngsw users [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
           [--model KEY] [--community STR] [--write-community STR]
           [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
           [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

services¶

show which management services are enabled

ngsw services [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
              [--model KEY] [--community STR] [--write-community STR]
              [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
              [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

show¶

show a full switch snapshot

ngsw show [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
          [--model KEY] [--community STR] [--write-community STR]
          [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
          [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

identify¶

detect the switch’s real model over SNMP

ngsw identify [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
              [--model KEY] [--community STR] [--write-community STR]
              [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
              [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

nsdp-device¶

show the raw NSDP device record (NSDP-capable models only)

ngsw nsdp-device [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                 [--model KEY] [--community STR] [--write-community STR]
                 [--nsdp-interface IFACE] [--http-password STR]
                 [--backend NAME] [--json] [-v]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

poe¶

show PoE status, or control a port’s PoE

ngsw poe [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
         [--model KEY] [--community STR] [--write-community STR]
         [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
         [--json] [-v] [--dry-run] [-y] [--force]
         [port] [{on,off,cycle,clear-fault}]

Positional Arguments¶

port

port number to control

action

Possible choices: on, off, cycle, clear-fault

PoE action for the given port

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

port¶

bring a port up or down

ngsw port [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
          [--model KEY] [--community STR] [--write-community STR]
          [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
          [--json] [-v] [--dry-run] [-y] [--force]
          port {up,down}

Positional Arguments¶

port

port number

state

Possible choices: up, down

admin state

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

describe¶

set or clear a port’s description (pass ‘’ to clear)

ngsw describe [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
              [--model KEY] [--community STR] [--write-community STR]
              [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
              [--json] [-v] [--dry-run] [-y] [--force]
              port description

Positional Arguments¶

port: port number
description: the label; ‘’ clears it

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

speed¶

force a port’s speed/duplex, or restore auto-negotiation

ngsw speed [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
           [--model KEY] [--community STR] [--write-community STR]
           [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
           [--json] [-v] [--duplex {full,half}] [--dry-run] [-y] [--force]
           port rate

Positional Arguments¶

port: port number
rate: ‘auto’, or a forced rate spelled as the switch does: 100, 10G. 1000 cannot be forced – 1000BASE-T requires auto-negotiation

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--duplex

Possible choices: full, half

duplex for a forced rate (default: full; ignored for ‘auto’)

Default: 'full'

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

flow-control¶

turn IEEE 802.3x flow control on or off for a port

ngsw flow-control [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                  [--model KEY] [--community STR] [--write-community STR]
                  [--nsdp-interface IFACE] [--http-password STR]
                  [--backend NAME] [--json] [-v] [--dry-run] [-y] [--force]
                  port {on,off}

Positional Arguments¶

port

port number

state

Possible choices: on, off

flow-control state

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

cycle-poe¶

power-cycle a port’s PoE

ngsw cycle-poe [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
               [--model KEY] [--community STR] [--write-community STR]
               [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
               [--json] [-v] [--dry-run] [-y] [--force]
               port

Positional Arguments¶

port: port number

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

clear-poe-fault¶

clear a port’s PoE fault state

ngsw clear-poe-fault [-h] [--config INVENTORY.toml] [--switch NAME]
                     [--host HOST] [--model KEY] [--community STR]
                     [--write-community STR] [--nsdp-interface IFACE]
                     [--http-password STR] [--backend NAME] [--json] [-v]
                     [--dry-run] [-y] [--force]
                     port

Positional Arguments¶

port: port number

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

upload-certificate¶

upload an HTTPS SSL certificate + private key

ngsw upload-certificate [-h] [--config INVENTORY.toml] [--switch NAME]
                        [--host HOST] [--model KEY] [--community STR]
                        [--write-community STR] [--nsdp-interface IFACE]
                        [--http-password STR] [--backend NAME] [--json] [-v]
                        --cert FILE --key FILE [--dry-run] [-y] [--force]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--cert

PEM certificate file

--key

PEM private-key file

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

upload-certificate-scp¶

deploy an HTTPS SSL certificate over SCP (FASTPATH M4300/GSM7252PS)

ngsw upload-certificate-scp [-h] [--config INVENTORY.toml] [--switch NAME]
                            [--host HOST] [--model KEY] [--community STR]
                            [--write-community STR] [--nsdp-interface IFACE]
                            [--http-password STR] [--backend NAME] [--json]
                            [-v] --scp-source USER@HOST[:PORT]
                            --scp-password-file FILE [--remote-dir DIR]
                            [--chain] [--dry-run] [-y] [--force]

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--scp-source

SCP source the switch pulls the staged PEM from

--scp-password-file

file holding the SCP source password

--remote-dir

directory on the SCP source holding the staged PEM(s)

Default: '/var/lib/switchcert/staging'

--chain

also copy the CA-chain PEM to nvram:sslpem-root

Default: False

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

pvid¶

set a port’s PVID

ngsw pvid [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
          [--model KEY] [--community STR] [--write-community STR]
          [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
          [--json] [-v] [--dry-run] [-y] [--force]
          port vlan

Positional Arguments¶

port: port number
vlan: VLAN id

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

vlan¶

create/delete VLANs or set membership

ngsw vlan [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
          [--model KEY] [--community STR] [--write-community STR]
          [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
          [--json] [-v]
          {set,create,delete} ...

Positional Arguments¶

vlan_cmd: Possible choices: set, create, delete

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

Sub-commands¶

set¶

set port VLAN membership

ngsw vlan set [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
              [--model KEY] [--community STR] [--write-community STR]
              [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
              [--json] [-v] [--dry-run] [-y] [--force]
              vlan port {untagged,tagged,excluded}

Positional Arguments¶

vlan
port
mode: Possible choices: untagged, tagged, excluded

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

create¶

create a VLAN

ngsw vlan create [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                 [--model KEY] [--community STR] [--write-community STR]
                 [--nsdp-interface IFACE] [--http-password STR]
                 [--backend NAME] [--json] [-v] [--dry-run] [-y] [--force]
                 vlan name

Positional Arguments¶

vlan
name

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

delete¶

delete a VLAN

ngsw vlan delete [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                 [--model KEY] [--community STR] [--write-community STR]
                 [--nsdp-interface IFACE] [--http-password STR]
                 [--backend NAME] [--json] [-v] [--dry-run] [-y] [--force]
                 vlan

Positional Arguments¶

vlan

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

ip¶

show or set the management IP

ngsw ip [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
        [--model KEY] [--community STR] [--write-community STR]
        [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
        [--json] [-v]
        {set} ...

Positional Arguments¶

ip_cmd: Possible choices: set

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

Sub-commands¶

set¶

set the management IP

ngsw ip set [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
            [--model KEY] [--community STR] [--write-community STR]
            [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
            [--json] [-v] [--dry-run] [-y] [--force]
            address netmask gateway

Positional Arguments¶

address
netmask
gateway

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

hostname¶

show or set the switch’s host name

ngsw hostname [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
              [--model KEY] [--community STR] [--write-community STR]
              [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
              [--json] [-v]
              {set} ...

Positional Arguments¶

hostname_cmd: Possible choices: set

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

Sub-commands¶

set¶

set the switch’s host name

ngsw hostname set [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                  [--model KEY] [--community STR] [--write-community STR]
                  [--nsdp-interface IFACE] [--http-password STR]
                  [--backend NAME] [--json] [-v] [--dry-run] [-y] [--force]
                  name

Positional Arguments¶

name

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

syslog¶

show remote-logging config, or turn it on/off

ngsw syslog [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
            [--model KEY] [--community STR] [--write-community STR]
            [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
            [--json] [-v]
            {set,add,remove} ...

Positional Arguments¶

syslog_cmd: Possible choices: set, add, remove

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

Sub-commands¶

set¶

turn remote logging on or off

ngsw syslog set [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                [--model KEY] [--community STR] [--write-community STR]
                [--nsdp-interface IFACE] [--http-password STR]
                [--backend NAME] [--json] [-v] [--dry-run] [-y] [--force]
                {on,off}

Positional Arguments¶

state: Possible choices: on, off

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

add¶

add a remote syslog collector

ngsw syslog add [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
                [--model KEY] [--community STR] [--write-community STR]
                [--nsdp-interface IFACE] [--http-password STR]
                [--backend NAME] [--json] [-v] [--port PORT] [--severity 0-7]
                [--dry-run] [-y] [--force]
                address

Positional Arguments¶

address: collector IP address or hostname

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--port

collector UDP port (default: 514)

Default: 514

--severity

Possible choices: 0, 1, 2, 3, 4, 5, 6, 7

forward messages at or above this severity (0 emergency .. 7 debug; default: 6 info)

Default: 6

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

remove¶

remove a remote syslog collector

ngsw syslog remove [-h] [--config INVENTORY.toml] [--switch NAME]
                   [--host HOST] [--model KEY] [--community STR]
                   [--write-community STR] [--nsdp-interface IFACE]
                   [--http-password STR] [--backend NAME] [--json] [-v]
                   [--dry-run] [-y] [--force]
                   address

Positional Arguments¶

address: collector IP address or hostname

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--dry-run

print the operation that would be sent, then send nothing

Default: False

-y, --yes

skip the confirmation prompt

Default: False

--force

override protected_ports and other force-gates

Default: False

capture¶

record a real switch’s state + protocol exchanges (opt-in, live)

ngsw capture [-h] [--config INVENTORY.toml] [--switch NAME] [--host HOST]
             [--model KEY] [--community STR] [--write-community STR]
             [--nsdp-interface IFACE] [--http-password STR] [--backend NAME]
             [--json] [-v] [--snapshot-only]
             output

Positional Arguments¶

output: output JSON file path

Named Arguments¶

--config

TOML inventory file

--switch

switch name from the inventory

--host

switch host (with –model)

--model

model key (with –host)

--community

SNMP read community override

--write-community

SNMP write community override

--nsdp-interface

network interface for NSDP (Plus switch) queries, e.g. eth0; overrides the inventory’s nsdp.interface when both are set

--http-password

web-UI/NSDP admin password for a Plus switch (HTTP + NSDP v1 auth share this one secret); overrides the inventory’s http.password when both are set

--backend

Possible choices: snmp, nsdp, http, ssh, telnet, console

--json

emit machine-readable JSON output

-v, --verbose

print tracebacks on error

--snapshot-only

record only the state snapshot (skip the live raw protocol walk)

Default: False

serve¶

Serve one or more in-repo mock switches on real sockets so an external tool can point at them when hardware is unavailable. Prints each switch’s bound port(s), SNMP community and HTTP password, then blocks until interrupted (SIGINT/SIGTERM).

ngsw serve [-h] [--model KEY] [--all] [--host IP] [--community STR]
           [--http-password STR] [--port N] [--http-port N]

Named Arguments¶

--model

model key to serve (repeatable); e.g. –model gsm7228ps

--all

serve every registered model

Default: False

--host

bind address (default 127.0.0.1; use 0.0.0.0 to expose off-host)

Default: '127.0.0.1'

--community

SNMP community the mock accepts (default: public)

Default: 'public'

--http-password

HTTP admin password the mock accepts (default: password)

Default: 'password'

--port

pin the SNMP/NSDP UDP port (default 0 = ephemeral; single model only)

Default: 0

--http-port

pin the HTTP TCP port (default 0 = ephemeral; single model only)

Default: 0

Recipes¶

Sweep an inventory for link state

for name in core edge lab; do
  echo "== $name"
  ngsw --switch "$name" ports --json | jq -r '.[] | select(.link_up) | .port'
done

Compare two protocols on the same switch

ngsw --switch core --backend snmp vlans --json > snmp.json
ngsw --switch core --backend http vlans --json > http.json
diff <(jq -S . snmp.json) <(jq -S . http.json)

Any difference is a real difference between what the two interfaces report — neither answer is a fallback from the other.

Identify an unknown switch

ngsw --host 10.1.5.99 --model gsm7252ps --community public identify

The --model is only a placeholder to carry the host and credentials; identify ignores it and asks the switch.

Capture a switch’s full state

ngsw --switch core capture core-2026-07-31.json

This is how the project’s fixtures and mock seeds are produced — see How the fake is built.

Run mock switches for another tool to talk to

ngsw serve --model gsm7228ps --model gs305ep

See Running mock switches.

ngsw command line¶

Selecting a switch¶

Choosing the protocol¶

Output¶

Write safety¶

Complete reference¶

Positional Arguments¶

Named Arguments¶

Sub-commands¶

models¶

Named Arguments¶

ports¶

Named Arguments¶

stats¶

Named Arguments¶

vlans¶

Named Arguments¶

pvids¶

Named Arguments¶

lldp¶

Named Arguments¶

macs¶

Named Arguments¶

sensors¶

Named Arguments¶

users¶

Named Arguments¶

services¶

Named Arguments¶

show¶

Named Arguments¶

identify¶

Named Arguments¶

nsdp-device¶

Named Arguments¶

poe¶

Positional Arguments¶

Named Arguments¶

port¶

Positional Arguments¶

Named Arguments¶

describe¶

Positional Arguments¶

Named Arguments¶

speed¶

Positional Arguments¶

Named Arguments¶

flow-control¶

Positional Arguments¶

Named Arguments¶

cycle-poe¶

Positional Arguments¶

Named Arguments¶

clear-poe-fault¶

Positional Arguments¶

Named Arguments¶

upload-certificate¶

Named Arguments¶

upload-certificate-scp¶

Named Arguments¶

pvid¶

Positional Arguments¶

Named Arguments¶

vlan¶

Positional Arguments¶

Named Arguments¶

Sub-commands¶

set¶

Positional Arguments¶

Named Arguments¶

create¶

Positional Arguments¶

Named Arguments¶

delete¶

Positional Arguments¶

Named Arguments¶

ip¶

Positional Arguments¶

Named Arguments¶

Sub-commands¶

`ngsw` command line¶