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