Skip to content

Working with plugins

NetBox plugins extend the OpenAPI schema. Because nsc builds its command tree from that schema at startup, every plugin endpoint becomes a command automatically — no per-plugin code in nsc.

How plugin endpoints surface

If a plugin registers tags: [my_plugin] and a path /api/plugins/my-plugin/widgets/, you get:

nsc my_plugin widgets list
nsc my_plugin widgets get 7
nsc my_plugin widgets create --field name=foo --apply

Verbs are derived from HTTP method + operationId exactly as for core endpoints. Custom action endpoints (POST /api/plugins/my-plugin/widgets/{id}/calibrate/) become e.g. nsc my_plugin widgets calibrate 7 --apply.

Discovery

nsc commands --schema <path-or-url> -o json | jq '.tags | keys'      # every tag
nsc commands --schema <path-or-url> -o json | jq '.tags.my_plugin'   # full subtree

nsc commands requires an explicit --schema (a path or URL to the OpenAPI document) and emits JSON only. The dumped tree is {info_title, info_version, schema_hash, tags: {<tag>: {resources: ...}}}.

Aliases across plugins

The tag-skipping aliases (ls, get, rm, search) resolve a resource name across every tag in the schema, plugin tags included — so nsc ls widgets finds my_plugin widgets without naming the tag, as long as the name is unambiguous. Singular forms only apply to the curated core resources (device, prefix, tenant, vlan, site, rack, interface, cable, tag); plugin resources are matched by their plural name as it appears in the schema.

Schema cache and plugin upgrades

The cache is keyed by the schema's SHA-256 hash, stored at ~/.nsc/cache/<profile>/<sha256>.json. When you upgrade a plugin (or any NetBox component that changes the schema), the next fresh schema fetch produces a new hash and a new cache file. Under the default daily refresh policy that fetch happens once the cache TTL (1 day) expires; force it sooner with the global --refresh-schema flag or nsc login --fetch-schema. The old <schema_hash>.json file becomes stale and gets cleaned by nsc cache prune — see Caching for the details.

When a plugin endpoint is missing

If nsc doesn't know about an endpoint you can hit with curl:

  1. Check nsc commands --schema <path-or-url> -o json | jq '.tags' | grep -i <name> — the schema may use a different tag than you expect.
  2. Re-run any command with the global --refresh-schema flag (or nsc login --profile <name> --fetch-schema) to force re-fetch the schema, bypassing the cache TTL.
  3. Confirm the endpoint is in /api/schema/?format=json for your install (some plugins generate routes lazily and don't register them with drf-spectacular).