Docs: thomaschristory.github.io/netbox-super-cli — the full guide, including install, first-run, guides, and the auto-generated CLI/config/exit-code reference.

Why

• Plugins just work. If your install has plugins, their endpoints appear as commands automatically.
• Multi-instance. Named profiles per NetBox instance, plus env-var overrides.
• Safe by default. POST/PATCH/PUT/DELETE preview as dry-runs unless you pass --apply.
• NetBox Branching. Stage changes in a branch (--branch, NSC_BRANCH, nsc branch use), review with nsc branch diff, merge with nsc branch merge --apply. See the guide.
• Agent-friendly. Deterministic command shape, machine-readable JSON output, stable error envelope with documented exit codes.
• Interactive TUI. nsc tui opens a keyboard-driven terminal UI — see below.

Install

uv tool install netbox-super-cli
# or, with pipx:
pipx install netbox-super-cli

Or from source:

git clone https://github.com/thomaschristory/netbox-super-cli
cd netbox-super-cli
uv sync
uv run nsc --version

Interactive TUI

nsc tui (aliases nsc interactive, nsc i) opens a full-screen, keyboard-driven UI over your NetBox — browse, filter, edit, bulk-edit and search across object types without writing a command. Like the CLI it is generated from the live schema, so it works for every resource and plugin.

nsc tui            # land on the resource picker
nsc tui devices    # jump straight into the devices list

Highlights: a collapsible resource picker, a web-UI-style filter builder (/), inline record editing with a confirm-diff save, schema-derived relationship drill-down, bulk edit with a per-record preview, a persisted column chooser (f) that lists each custom field individually, and global search (Ctrl+F). The same dotted paths work on the CLI: nsc ls devices --columns id,name,custom_fields.rack_role. Full walkthrough in the Interactive TUI guide.

Reading

export NSC_URL=https://netbox.example.com
export NSC_TOKEN=$(cat ~/.netbox-token)

uv run nsc dcim devices list
uv run nsc dcim devices list --site-id 42 --status active --all --output json
uv run nsc dcim devices get 7
uv run nsc circuits providers list --output csv
uv run nsc ipam prefixes list --filter created__gte=2026-01-01 --output yaml

Saved searches

Filter sets you save from the TUI (Ctrl+W in the filter builder) are stored as NetBox native saved filters (extras.saved-filters), scoped to the resource's object type. A search you save in nsc shows up in the NetBox web UI's filter dropdown for that object — and a filter saved in the web UI loads in the TUI (Ctrl+O) — so the two are fully interchangeable. Re-apply one on the CLI with --saved:

uv run nsc dcim devices list --saved active-switches
# explicit --filter / typed options override the saved values:
uv run nsc dcim devices list --saved active-switches --status offline

When NetBox is unreachable (offline, or missing permission on extras.savedfilter), nsc transparently falls back to a local store under saved_searches in ~/.nsc/config.yaml, keyed by tag/resource, and tells you it did so.

Object colors

NetBox assigns colors to roles, tags, and similar fields. In table output nsc renders those values in their NetBox-defined colors:

uv run nsc dcim devices list                      # colored when stdout is a TTY
uv run nsc dcim devices list --no-object-colors   # plain text

Toggle it independently of --color with the object_colors setting (auto/on/off) or the --object-colors/--no-object-colors flag. off, NO_COLOR, and non-TTY output are always respected, so piped or redirected output stays uncolored.

Writing

# Dry-run by default — shows the resolved request without sending it.
uv run nsc dcim devices create -f device.yaml --explain

# Commit with --apply.
uv run nsc dcim devices create -f device.yaml --apply

# Bulk create: one HTTP call when the schema supports it, sequential loop otherwise.
uv run nsc dcim devices create -f devices.yaml --apply
uv run nsc dcim devices create -f devices.yaml --no-bulk --on-error continue --apply

# Speed up a loop-mode bulk write with concurrent requests (default 1, max 32).
# Per-record --on-error semantics hold; the audit log stays one line per record.
uv run nsc dcim devices create -f devices.ndjson --workers 8 --apply

# NDJSON / JSONL — one record per line; parse failures abort the whole batch
# before any wire request fires (`type: input_error`, exit 4, `details.bad_lines`).
uv run nsc dcim devices create -f devices.ndjson --apply
cat devices.ndjson | uv run nsc dcim devices create -f - --apply

# Per-field overrides (CLI wins over file on overlap).
uv run nsc dcim devices update 42 --field status=active --apply

# Delete; default is exit-0 if already gone, --strict turns missing-id into exit 9.
uv run nsc dcim devices delete 42 --apply
uv run nsc dcim devices delete 42 --apply --strict

Every write attempt — dry-run included — appends one line to ~/.nsc/logs/audit.jsonl; the most recent exchange is also mirrored to ~/.nsc/logs/last-request.json.

Bulk input formats

Stdin is sniffed from the first 512 bytes (first non-whitespace byte plus a one-object lookahead for newline-then-{). NDJSON parse failures collect up to 20 bad_lines and abort before any wire request; --no-bulk still forces a loop fallback for any bulk shape.

Audit log sensitivity

audit.jsonl is confidential (not secret). It records what was sent — record-level data your account had write access to. The CLI redacts:

• HTTP headers in the SENSITIVE_HEADERS set (e.g. Authorization, X-API-Key) — replaced with "<redacted>".
• Request-body fields whose OpenAPI definition has format: password OR whose name (case-insensitive) is one of: password, secret, token, api_key, apikey, private_key, passphrase, client_secret. Nested fields and arrays of objects are walked recursively.

The wire body sent to NetBox is not redacted — only the audit log. A failed write still records the redacted body; redaction is irreversible. Treat audit.jsonl like a verbose application log: gate it behind your home-directory permissions and rotate / archive accordingly.

For a stricter posture, set audit_redaction: full in ~/.nsc/config.yaml (the default is safe, the field-level redaction described above). In full mode every audit line keeps only {method, url, status_code, timestamp, profile} — all request and response bodies are dropped, and the url is sanitized (query string and any user:pass@ credentials stripped).

NetBox Branching

If your NetBox runs the Branching plugin, any command can stage its changes in a branch for review:

nsc branch create add-london --use            # create, wait until ready, make it sticky
nsc dcim sites create -f london.yaml --apply  # lands in the branch; stderr shows "⎇ branch: add-london"
nsc branch diff                               # review the staged changes
nsc branch merge                              # dry-run, validated server-side
nsc branch merge --apply                      # merge into main
nsc branch use --main                         # back to main

--branch NAME and NSC_BRANCH select a branch for a single command or a whole shell, and agents should use these. A merged, missing or not-ready branch fails loudly and never falls back to main. See the branching guide.

Curated aliases

nsc ls, nsc get, nsc rm, and nsc search are short verbs over the dynamic command tree.

nsc ls devices                 # list a resource by plural name
nsc ls device                  # singular also works (curated set, see below)
nsc get devices 7              # one record by id or name
nsc rm devices 7 --apply       # delete (dry-run by default)
nsc search "rack-42"           # /api/search/ on NetBox 4.5+

Singular forms resolve for a curated set of nine resources: device, prefix, tenant, vlan, site, rack, interface, cable, and tag. Any other singular that does not resolve suggests its plural ("Did you mean devices?").

Output and errors

• --output {table,json,yaml,csv,jsonl}. Table is the default on a TTY; JSON is the default when stdout is piped.
• On --output json, the records array is emitted directly (no NetBox-style count/results wrapper); single-record writes emit the resulting record dict.
• Failures emit a stable ErrorEnvelope (JSON to stdout on --output json, Rich panel to stderr otherwise) with type ∈ {auth, not_found, validation, conflict, rate_limited, server, transport, schema, config, client, internal, ambiguous_alias, unknown_alias, input_error} and a documented exit code per type. See CHANGELOG.md and the spec for the full table.

Schema introspection

# Dump every endpoint in the bundled NetBox schema as JSON.
uv run nsc commands --schema nsc/schemas/bundled/netbox-4.6.0.json.gz --output json | head

# Or against a live install.
uv run nsc commands --schema https://netbox.example.com/api/schema/?format=json --output json

Cache management

The on-disk command-model cache lives at ~/.nsc/cache/<profile>/<schema-hash>.json and is regenerated automatically when the live NetBox schema changes. Over time, removed profiles or upgraded NetBox versions can leave orphan entries behind.

nsc cache prune                          # show what would be deleted (dry-run)
nsc cache prune --apply                  # actually delete
nsc cache prune --max-age 30 --apply     # also delete cache files older than 30 days
nsc cache prune --output json            # structured envelope for scripts

What gets pruned:

1. Cache directories for profiles that are no longer in your config.
2. Cache files whose schema-hash differs from the live NetBox schema (skipped per-profile when offline).
3. With --max-age <days>: cache files older than the threshold (excludes files already covered by rule 1).

The adhoc cache directory (used by env-var-only invocations like NSC_URL=… nsc dcim devices list) is never pruned automatically.

Shell completion

nsc ships static completion stubs that complete subcommands and option names.

nsc --install-completion         # auto-detects $SHELL
nsc --show-completion            # prints the script instead of installing

Typer supports bash, zsh, fish, and pwsh.

Completion of dynamic values reads the cached schema and complements the static stubs above:

nsc ls dev<TAB>                               # devices device-roles device-types
nsc --profile <TAB>                           # configured profile names
nsc dcim devices list --status <TAB>          # enum values for the field

Bundled Skill for AI agents

nsc ships a portable Skill bundle at skills/netbox-super-cli/SKILL.md that briefs an AI agent on how to drive nsc correctly (dry-run discipline, JSON output, error envelope, audit log).

nsc skill install --target claude-code            # dry-run; prints the destination
nsc skill install --target claude-code --apply    # actually copies

# Or export to an arbitrary directory (e.g. CI or a shared-skill repo).
nsc skill export ./skills                          # dry-run; prints the would-write path
nsc skill export ./skills --apply                  # writes ./skills/netbox-super-cli/SKILL.md

skill install targets: claude-code, codex, gemini, copilot. Where a target has no documented programmatic install path, the helper prints actionable manual instructions instead of guessing. skill export <dir> always writes to <dir>/netbox-super-cli/SKILL.md and, like install, is dry-run unless you pass --apply.

License

Apache 2.0.