Dynamic Commands

Every NetBox resource reachable through the API is automatically registered as a Typer subcommand, derived from the bundled OpenAPI schema at import time. This means --help works at every level and shell completion is fully supported.

---

Command structure

nbx <group> <resource> <action> [options]

For example:

nbx dcim devices list
nbx dcim devices get --id 1
nbx ipam prefixes create --body-json '{...}'

---

Discovery

Use the discovery commands to explore what's available:

# All app groups
nbx groups
# → circuits, core, dcim, extras, ipam, plugins, tenancy, users, virtualization, vpn, wireless

# Resources in a group
nbx resources dcim
# → cable-terminations, cables, console-ports, device-bays, device-roles, devices, …

# Help at any level
nbx dcim --help
nbx dcim devices --help
nbx dcim devices list --help

---

Actions

Action	HTTP method	Path	Notes
list	GET	/api/<group>/<resource>/	Returns paginated list
get	GET	/api/<group>/<resource>/{id}/	Requires --id
create	POST	/api/<group>/<resource>/	Requires --body-json or --body-file
update	PUT	/api/<group>/<resource>/{id}/	Requires --id and body
patch	PATCH	/api/<group>/<resource>/{id}/	Requires --id and body
delete	DELETE	/api/<group>/<resource>/{id}/	Requires --id

Not every resource supports all actions — availability depends on the OpenAPI schema.

---

Options (all actions)

Flag	Description
--id INTEGER	Object ID for detail operations (get, update, patch, delete)
-q / --query KEY=VALUE	Query string filter (repeatable)
--body-json TEXT	Inline JSON request body
--body-file PATH	Path to JSON file for request body
--json	Output raw JSON
--yaml	Output YAML
--trace	Fetch and render ASCII cable trace (interfaces only, get only)

---

Filtering

The -q / --query flag maps to NetBox API query parameters:

nbx dcim devices list -q site=nyc01
nbx dcim devices list -q status=active -q role=spine
nbx ipam prefixes list -q family=6 -q status=active
nbx dcim interfaces list -q device_id=1

Multiple -q flags are ANDed together.

---

Output formats

Rich table (default)JSONYAML

nbx dcim devices list

Renders a Rich table with prioritized columns: id, name, status, site, role, type, etc.

nbx dcim devices list --json

Prints the raw paginated API response as indented JSON. Useful for piping to jq.

nbx dcim devices list --yaml

Renders the response as YAML.

---

Cable trace

For dcim/interfaces, the get action supports --trace to fetch and display the cable path as an ASCII diagram:

nbx dcim interfaces get --id 4 --trace

Output:

Cable Trace:
┌────────────────────────────────────┐
│         dmi01-akron-rtr01          │
│       GigabitEthernet0/1/1         │
└────────────────────────────────────┘
                │
                │  Cable #36
                │  Connected
                │
┌────────────────────────────────────┐
│       GigabitEthernet1/0/2         │
│         dmi01-akron-sw01           │
└────────────────────────────────────┘

Trace Completed - 1 segment(s)

---

Demo profile variant

The same dynamic command tree is registered under nbx demo and targets demo.netbox.dev:

nbx demo dcim devices list
nbx demo ipam prefixes list
nbx demo dcim interfaces get --id 4 --trace

See Demo Profile for setup.

---

How it works

At startup, _register_openapi_subcommands() in cli.py reads reference/openapi/netbox-openapi.json, builds a SchemaIndex, then creates a Typer sub-app for every group, a nested sub-app for every resource, and a command for every supported action. The same registration runs twice — once for the root app and once for demo_app with _get_demo_client as the client factory.

For plugin resources, the bundled schema gives nbx the static command tree it knows about, and the TUI layer can additionally augment that view at runtime by discovering live /api/plugins/ REST endpoints from the connected NetBox instance.