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

Each /api/plugins/<plugin>/<resource>/ path becomes its own resource. NetBox tags every plugin endpoint with the generic plugins tag; nsc then groups them under the plugin's URL segment instead. For example, NetBox Branching's /api/plugins/branching/branches/ and /api/plugins/branching/changes/ give:

nsc branching branches list
nsc branching branches merge-create 3 --apply
nsc branching changes list --branch <schema_id>

A plugin that sets its own tag keeps it. With 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

A built-in command with the same name (for example branch) takes precedence over a plugin group.

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.

Plugins with first-class support

A few plugins change how every request behaves, not just add endpoints. For those, nsc has built-in commands:

  • NetBox Branching (netboxlabs-netbox-branching): --branch / NSC_BRANCH / nsc branch …. See NetBox Branching. The plugin's own endpoints still appear as dynamic commands under its tag when the live schema includes them. Prefer nsc branch, which resolves names, waits for jobs and is dry-run by default.

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