Concepts¶
A short tour of the model nsc uses for everything.
Profiles¶
A profile is a named NetBox instance: URL + token + a few options. They live
in ~/.nsc/config.yaml:
default_profile: prod
profiles:
prod:
name: prod
url: https://netbox.example.com
token: !env NSC_PROD_TOKEN
verify_ssl: true
lab:
name: lab
url: https://netbox-lab.local
token: !env NSC_LAB_TOKEN
verify_ssl: false
Pick one with --profile <name>, override at the command line with --url /
--token, or skip the file entirely with NSC_URL + NSC_TOKEN env vars
("adhoc" mode). See Managing profiles.
Dynamic command tree¶
The command tree is built at startup from the live NetBox OpenAPI schema:
nsc <tag> <resource> <verb> [args] [options]
│ │ │
│ │ └── derived from HTTP method + operationId:
│ │ GET /things/ → list
│ │ GET /things/{id}/ → get
│ │ POST /things/ → create
│ │ PATCH /things/{id}/ → update
│ │ PUT /things/{id}/ → replace
│ │ DELETE /things/{id}/ → delete
│ └── path segment (e.g., devices, prefixes)
└── OpenAPI tag (e.g., dcim, ipam)
This means every endpoint your install exposes is a command — including plugin
endpoints — without per-plugin code in nsc.
A short curated alias layer sits on top: nsc ls, nsc get, nsc rm, nsc search.
For the curated resources — device, prefix, tenant, vlan, site,
rack, interface, cable, tag — the singular works identically to the
plural: nsc ls device is the same as nsc ls devices (likewise for get and
rm where supported). A non-curated singular that doesn't resolve suggests the
plural instead ("Did you mean devices?").
Dry-run / apply¶
Writes default to dry-run. The CLI shows the resolved request and exits 0 WITHOUT sending it.
nsc dcim devices create --field name=foo --field site=1
# → JSON of what would be sent
nsc dcim devices create --field name=foo --field site=1 --apply
# → actually sends
Add --explain to a dry-run to see the schema reasoning ("PATCH because of
operationId dcim_devices_partial_update").
Branches (NetBox Branching)¶
If your server runs the NetBox Branching plugin, any command can run inside a
branch instead of main. Pick one with --branch NAME, NSC_BRANCH=NAME, or
make it sticky on the profile with nsc branch use NAME. While a branch is
active, every command prints ⎇ branch: NAME on stderr. If the branch can't be
used (merged, missing, not ready), the command fails without sending anything.
It never quietly falls back to main. See NetBox Branching.
nsc branch create add-london --use
nsc dcim sites create --field name=London --field slug=london --apply # staged in the branch
nsc branch diff
nsc branch merge --apply
Audit log¶
Every wire request and its response are appended to
~/.nsc/logs/audit.jsonl. Sensitive fields (password, token, …) are
redacted before write — the live wire body is never modified. See
Writes and safety for the full contract.
Error envelope¶
When something goes wrong with --output json, nsc emits a single-line JSON envelope:
{
"error": "human message",
"type": "validation",
"endpoint": "https://...",
"method": "POST",
"status_code": 400,
"operation_id": "dcim_devices_create",
"details": { ... }
}
Each type maps to a stable exit code (see Exit codes).
The contract is locked — type values and exit codes do not change once
shipped.